@salaros/ai-harness 0.5.1 → 0.6.0

package/README.md

@@ -10,7 +10,7 @@ It assumes no language or framework. What you put in `src/` decides the stack.
 - **Skills**: 60 vendored [agent skills](https://skills.sh) for requirements, design, testing, code review and more.
 - **Agents**: `engineer`, `business-analyst`, `devops` and `assistant`, each routing work to the right skills.
 - **Hooks**: agent hooks block dangerous shell commands and check every edit. Git hooks check commit messages, the documentation chain and formatting.
-- **A documentation chain**: BRD → PRD → EARS → BDD → ADR → SPEC → TDD → plan → code, with a checker that keeps every document traceable to the one before it.
+- **A documentation chain**: PDD → BRD → PRD → TRD → EARS → BDD → RFC → ADR → SPEC → TDD → plan → code, with a checker that keeps every document traceable to the one before it.
 
 ## Requirements
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salaros/ai-harness",
-  "version": "0.5.1",
+  "version": "0.6.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"
@@ -12,6 +12,7 @@
     "scripts/project-facts.js",
     "scripts/repo-view.js",
     "scripts/repo-edit.js",
+    "scripts/plan-entry.js",
     "README.md",
     "LICENSE"
   ],

package/scripts/install-policy.js

@@ -5,6 +5,7 @@
 //   const policy = require("./install-policy");
 //   const { policy: name, asked } = policy.policyFor(rows, file, wants);
 //   const { outcome, bucket, write, silent } = policy.decide(name, facts, reads);
+//   const entries = policy.decideRoster(name, roster, 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
@@ -21,7 +22,18 @@
 // 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.
+//
+// One policy is decided for a folder rather than for a path: skills, where the unit a project
+// installs is the skill and one line of output stands for its several hundred files. decideRoster
+// takes every path the manifest gave that policy, each as the upstream's listing holds it
+// ({ file, link, exec }), and answers in plan entries, because a folder's answer is several paths
+// whose reporting differs between them. Its `reads` are the same kinds of thing by another shape,
+// one path at a time:
+//   reads  exists(file)   the target has something at the path
+//          theirs(file)   the upstream's content at the head: LF text, a Buffer, or null
+//          held(file)     the target's copy as bytes, or null when it has none
 const lib = require("./lib");
+const entry = require("./plan-entry");
 
 // ---------------------------------------------------------------- the manifest
 
@@ -297,6 +309,13 @@ function layDown(existing) {
 
 // ---------------------------------------------------------------- the policies
 
+// Every summary list a path can join, named where the policies that answer with them are written.
+// The summary used to keep its own copy, so a policy answering with a name that copy did not have
+// threw at the push rather than being reported. UNFINISHED is the ones that leave work for the
+// reader, which is what makes a run exit 1.
+const BUCKETS = ["written", "merged", "conflicted", "seeded", "kept", "skipped", "template", "unreadable"];
+const UNFINISHED = ["conflicted", "unreadable"];
+
 const POLICIES = {
     merge: merging("merge"),
     reconcile: merging("reconcile"),
@@ -315,10 +334,81 @@ const POLICIES = {
     template: () => ({ outcome: "template", bucket: "template", silent: true }),
 };
 
+// ---------------------------------------------------------------- deciding a whole folder
+
+const SKILLS = ".agents/skills/";
+const SKILLS_LOCK = "skills-lock.json";
+
+// 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 skills(roster, reads) {
+    const theirLock = JSON.parse(reads.theirs(SKILLS_LOCK) || '{"skills":{}}');
+    const ourBytes = reads.held(SKILLS_LOCK);
+    const ourLock = ourBytes === null ? { skills: {} } : JSON.parse(ourBytes.toString("utf8"));
+    ourLock.skills = ourLock.skills || {};
+    const mine = new Set(Object.keys(ourLock.skills));
+
+    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, link, exec } of roster) {
+        // A skill link is relink's to make, once the directory it lives in exists: relink knows which
+        // skills this project actually has, where the upstream only knows its own.
+        if (link) { out.push(entry.folder(file, entry.quiet())); continue; }
+        if (!file.startsWith(SKILLS)) continue;
+        const name = file.slice(SKILLS.length).split("/")[0];
+        const tally = seen(name);
+        tally.files++;
+        const exists = reads.exists(file);
+        // A script the skill runs keeps its executable bit whoever owns the content, as a hook does.
+        if (exec && exists) out.push(entry.marked(file, entry.quiet()));
+        // 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 theirs = reads.theirs(file);
+        if (theirs === null) continue;
+        // 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 ? reads.held(file) : null;
+        let write;
+        if (Buffer.isBuffer(theirs)) {
+            if (lib.sameContent(held, theirs)) continue;
+            write = theirs;
+        } else {
+            const ours = held === null ? null : held.toString("utf8");
+            if (ours !== null && lib.toLf(ours) === theirs) continue;
+            write = lib.asFound(theirs, ours !== null && lib.isCrlf(ours));
+        }
+        if (exists) tally.updated++; else tally.added++;
+        out.push(entry.written(file, write, entry.quiet(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";
+        out.push(entry.noted(`${SKILLS}${name}  (${t.files} file(s))`, entry.shown("skills", "100644", what)));
+    }
+    for (const [name, pinned] of Object.entries(theirLock.skills)) {
+        if (!ourLock.skills[name]) ourLock.skills[name] = pinned;
+    }
+    out.push(entry.written(SKILLS_LOCK, JSON.stringify(ourLock, null, 2) + "\n", entry.quiet()));
+    return out;
+}
+
+const ROSTER_POLICIES = { skills };
+
 function decide(policy, facts, reads = {}) {
+    if (ROSTER_POLICIES[policy]) throw new Error(`install-policy: "${policy}" is decided for a whole folder, so ask decideRoster for its roster`);
     const rule = POLICIES[policy];
     if (!rule) throw new Error(`install-policy: no policy named "${policy}"`);
     return rule(facts, reads);
 }
 
-module.exports = { policyFor, decide };
+// `roster` is every path the manifest gave this policy, as the upstream's listing holds it.
+function decideRoster(policy, roster, reads = {}) {
+    const rule = ROSTER_POLICIES[policy];
+    if (!rule) throw new Error(`install-policy: no policy named "${policy}" is decided for a whole folder`);
+    return rule(roster, reads);
+}
+
+module.exports = { policyFor, decide, decideRoster, BUCKETS, UNFINISHED };

package/scripts/plan-entry.js

@@ -0,0 +1,80 @@
+// scripts/plan-entry.js
+// One line of an install plan: at most one thing done to one path, and how the run reports it.
+//
+// An install rewrites somebody else's repository, and it decides everything before it writes
+// anything, so the plan is the whole of what a run is. Its entries used to be a record with eleven
+// optional keys, built in three places and read in three others, with the rules for both written out
+// as a comment above the loop. A comment is not checked: apply() padded `policy` on every entry not
+// marked silent, so a producer that left the column out would have thrown halfway through somebody's
+// repo, at print time, with no way to tell which producer built the entry.
+//
+// The kinds below are the whole vocabulary an install plan needs. Each says what is done to the path
+// -- four of the five words repo-edit.js reads, write, link, mkdir and mark, plus doing nothing at
+// all -- and carries
+// how it is reported, which is either `shown(...)`, four columns demanded where the entry is made,
+// or `quiet(...)`, counted in the summary and never printed. Nothing here touches a repo, prints, or
+// decides an outcome word: repo-edit does the first, the run does the second, install-policy the
+// third.
+
+// How an entry is reported: the policy the manifest gave the path, the mode Git recorded, the
+// outcome word, and the summary list the path joins. The bucket is the one that may be left out -- a
+// line can be printed and belong to no list, which is what "unchanged" is. The other three are the
+// line, so leaving one out is refused here, by name, rather than at the padEnd that would have hit it.
+function shown(policy, mode, outcome, bucket = null) {
+    for (const [name, value] of [["policy", policy], ["mode", mode], ["outcome", outcome]]) {
+        if (typeof value !== "string" || !value) throw new Error(`a plan entry that is printed needs a ${name}`);
+    }
+    return { policy, mode, outcome, bucket };
+}
+
+// Counted in the summary and never printed: a skill's own files, where the skill is the line and its
+// four hundred files are not; the two receipts; the folder made for a link.
+const quiet = (bucket = null) => ({ silent: true, bucket });
+
+// A section of the output. Heads the lines that follow it and does nothing to any path.
+const heading = phase => ({ phase });
+
+const at = (file, as, act) => {
+    if (typeof file !== "string" || !file) throw new Error("a plan entry needs the path it is about");
+    if (!as || (!as.silent && !as.outcome)) throw new Error(`${file}: a plan entry needs either shown(...) or quiet(...)`);
+    return { file, ...act, ...as };
+};
+
+// The path is left exactly as it was found, and the line says so: unchanged, yours, UNREADABLE, or a
+// skill whose folder nothing in this run touched.
+const noted = (file, as) => at(file, as, {});
+
+// `text` is what the path will hold, a string or a Buffer. `exec` marks it executable as well, which
+// is part of the same entry rather than a second one: a hook written 100644 gates nothing and looks
+// installed either way.
+const written = (file, text, as, { exec = false } = {}) => at(file, as, { write: text, exec });
+
+// A symlink to `to`. `replace` clears whatever is in its way first, which is how a link checked out
+// as a regular file -- the failure that leaves an agent seeing no skills at all -- gets undone.
+const linked = (file, to, as, { replace = false } = {}) => at(file, as, { link: to, replace });
+
+// The executable bit alone, for a path whose content is somebody else's to keep.
+const marked = (file, as) => at(file, as, { exec: true });
+
+// The folder and nothing in it, for a link whose parent has to exist before it can be made.
+const folder = (file, as) => at(file, as, { mkdir: true });
+
+// The run's line for an entry, or null for one that prints nothing. One function rather than a
+// format string at each consumer, so the widths and the rule for what is printed live with the
+// record they are about.
+// A column is its word, a space, and then padding out to the width: padding alone lines the columns
+// up only while every word is shorter than its column, and "reconcile" filled a nine-wide policy
+// column exactly while "yours appended" overran a twelve-wide outcome, so both ran into what came
+// after them. A word too long now pushes its column out of line, which is a worse-looking line and
+// a readable one. Nothing noticed either way for as long as a run's lines could be read only as the
+// stdout of a real install.
+const column = (word, width) => `${word} `.padEnd(width);
+const describe = e => (e.phase || e.silent ? null : `  ${column(e.policy, 9)}${e.mode}  ${column(e.outcome, 12)}${e.file}`);
+
+// The entry as it turned out, when that is not what it planned. The only case is a symlink the
+// platform refused: the edit reports the link is not there, and which outcome word that deserves is
+// the run's to say. A copy, and only the reporting changes -- what was asked of the path is what was
+// asked, whatever became of it.
+const turnedOut = (e, outcome, bucket = null) => ({ ...e, outcome, bucket });
+
+module.exports = { shown, quiet, heading, noted, written, linked, marked, folder, describe, turnedOut };

package/scripts/repo-edit.js

@@ -5,7 +5,7 @@
 //   apply(entries)  carry out a finished plan, and return what became of it
 // Each entry that asks for work gets one result:
 //   { file, kind, done, why }
-// `kind` is write, link, mkdir or mark; `done` is whether the tree now holds what the entry asked
+// `kind` is write, link, mkdir, mark or move; `done` is whether the tree now holds what the entry asked
 // for; `why` is the mechanical reason it does not, or null. No outcome word and no summary bucket
 // appears here: those are the install policy's, and the run translates these results into them.
 // Nothing here prints or exits, so a refusal is a value the caller reads rather than a message a
@@ -20,9 +20,29 @@ const git = (root, args) => spawnSync("git", ["-c", "core.longpaths=true", "-C",
 
 const result = (file, kind, why) => ({ file, kind, done: !why, why: why || null });
 
+// A move's two refusals, worded once. Both adapters answer the same question and have to answer it
+// the same way, which is easier to keep true when there is one sentence rather than two copies.
+const noSource = e => `nothing at ${e.move} to move to ${e.file}`;
+const taken = e => `${e.file} is already there, so ${e.move} was left where it is`;
+// The third, for the step where the rename is done and Git will not record it: worded once for the
+// same reason, and carrying the command's own words, since what Git refused is the whole of what
+// there is to say about it.
+const cannotStage = (e, r) => `could not stage the move of ${e.move} to ${e.file}: ${(r.stderr || "").trim()}`;
+// A path a move in the same plan is moving to, claimed by some other entry as well. A plan that
+// says two things about one path is a plan that contradicts itself, and the second of them is
+// refused rather than performed: see `apply`, where the reason this can arise at all is set out.
+const landed = (e, from) => `${e.file} is where ${from} was moved, so nothing else in the plan writes there`;
+// A symlink that was not made, worded as the filesystem words it, because that is what the disk
+// adapter is reporting: EEXIST for a path something is already at, EPERM for a platform that will
+// not make one at all.
+const noLink = (e, code) => `could not create the symlink ${e.file} -> ${e.link}: ${code}`;
+
 // What an entry asks to have done, or null when it asks for nothing: a phase heading, or a path the
 // plan decided to leave exactly as it found it.
 function work(e) {
+    // Before the rest, because a move is about a path that does not exist yet and the entry naming
+    // it may well go on to link something at where it came from.
+    if (e.move !== undefined) return "move";
     if (e.link !== undefined) return "link";
     if (e.write !== undefined) return "write";
     if (e.mkdir) return "mkdir";
@@ -39,10 +59,27 @@ function editing(act) {
     return {
         apply(entries) {
             const out = [];
-            for (const e of entries) {
+            // W-2. A move empties a path, and an entry that links something at where it came from
+            // reads naturally after it -- so a caller writes it that way and the edit, not the
+            // caller, is what makes the order safe. Left in the caller's order, the link ran first,
+            // `clear` took the project's own folder out of the way, and the move then carried the
+            // link off to the destination: work destroyed, with both entries reporting success.
+            // Moves go first instead, which is the order every caller already writes. The one thing
+            // it costs: a move's source has to be in the tree already, not written by the same plan.
+            const moves = entries.filter(e => work(e) === "move");
+            // And what the reordering itself costs, paid here rather than by the caller. A move now
+            // runs before an entry written above it, so the path it lands on is a path that entry
+            // was about to land on -- and if that entry is a link, `clear` takes the moved work out
+            // of its way: the same destruction, one end of the move further along. A move owns both
+            // ends of its path, so the rest of the plan is refused at the destination. A mark is not
+            // refused: it changes the mode of whatever is at the path rather than putting something
+            // else there, which is how a hook is moved into place and then made executable.
+            const to = new Map(moves.map(e => [e.file, e.move]));
+            for (const e of [...moves, ...entries.filter(e => work(e) !== "move")]) {
                 const kind = work(e);
                 if (!kind) continue;
-                let why = kind === "mark" ? null : act[kind](e);
+                const onAMove = kind !== "move" && kind !== "mark" && to.has(e.file);
+                let why = onAMove ? landed(e, to.get(e.file)) : kind === "mark" ? null : act[kind](e);
                 if (!why && e.exec) why = act.mark(e);
                 out.push(result(e.file, kind, why));
             }
@@ -67,17 +104,55 @@ function mapEdit(files = {}, { links = true } = {}) {
     const held = { ...files };
     const marked = [];
     const view = () => repoView.fromMap(held);
+    // Every key a path stands for: the file itself, and everything under it when it is a folder.
+    // A map has no directories, so this is what "something is at this path" means here.
+    const anyUnder = rel => [rel, ...Object.keys(held).filter(k => k.startsWith(`${rel}/`))].filter(k => k in held);
+    // The ancestor a path cannot be reached through, because the map holds a file there. A map has
+    // no folders to be blocked by, so this is the only shape in which "a file where a folder has to
+    // go" exists here at all -- and on disk it is what makes mkdir and the write after it refuse.
+    const ancestorFile = rel => rel.split("/").slice(0, -1)
+        .map((_, i, parts) => parts.slice(0, i + 1).join("/"))
+        .find(p => p in held) || null;
     return {
         ...editing({
-            write: e => { held[e.file] = e.write; return null; },
+            // A folder at the path is a refusal, which in a map is keys under it: the disk answers
+            // EISDIR, and an adapter that quietly wrote instead would be the one place the suite
+            // could not see the failure an install really gets.
+            write: e => {
+                if (anyUnder(e.file).some(k => k !== e.file)) return `could not write ${e.file}: EISDIR`;
+                if (ancestorFile(e.file)) return `could not write ${e.file}: ENOTDIR`;
+                held[e.file] = e.write;
+                return null;
+            },
             link: e => {
-                if (!links) return `could not create the symlink ${e.file} -> ${e.link}: EPERM`;
+                if (!links) return noLink(e, "EPERM");
+                if (ancestorFile(e.file)) return noLink(e, "ENOTDIR");
+                // A file or a link at the path is replaced and a folder holding anything is not,
+                // because that is what the disk does: `clear` unlinks, and its rmdir fallback fails
+                // on a folder with something in it, so the symlink then refuses with EEXIST.
+                if (anyUnder(e.file).some(k => k !== e.file)) return noLink(e, "EEXIST");
                 held[e.file] = { link: e.link };
                 return null;
             },
             // A map holds files, and a folder in it is whatever a path implies, so there is nothing
-            // to make: the entry is satisfied the moment anything is written under it.
-            mkdir: () => null,
+            // to make: the entry is satisfied the moment anything is written under it. A file at the
+            // exact path is the one case with an answer to give, and it is the disk's.
+            mkdir: e => {
+                if (e.file in held) return `could not create the folder ${e.file}: EEXIST`;
+                return ancestorFile(e.file) ? `could not create the folder ${e.file}: ENOTDIR` : null;
+            },
+            // A folder in a map is a prefix, so moving one is re-keying every path under it, and a
+            // file is the exact key. Whatever each one held travels with it, mode and all.
+            move: e => {
+                const from = anyUnder(e.move);
+                if (!from.length) return noSource(e);
+                if (anyUnder(e.file).length) return taken(e);
+                for (const key of from) {
+                    held[`${e.file}${key.slice(e.move.length)}`] = held[key];
+                    delete held[key];
+                }
+                return null;
+            },
             mark: e => {
                 const row = view().modes().find(r => r.file === e.file);
                 if (!row) return `nothing at ${e.file} to mark executable`;
@@ -98,7 +173,49 @@ function mapEdit(files = {}, { links = true } = {}) {
 function worktreeEdit(root) {
     const at = rel => path.resolve(root, String(rel));
     const parent = rel => fs.mkdirSync(path.dirname(at(rel)), { recursive: true });
-    const clear = rel => { try { fs.unlinkSync(at(rel)); } catch { /* nothing was in the way */ } };
+    // rmdir after unlink, because a directory symlink on Windows -- and a junction, which is what
+    // `npx skills` leaves behind -- is a directory to unlink and a link to rmdir, and only one of the
+    // two calls works on either. Without the second, replacing a junction with a relative symlink
+    // fails at the symlink for want of clearing its way.
+    const clear = rel => {
+        try { fs.unlinkSync(at(rel)); } catch { try { fs.rmdirSync(at(rel)); } catch { /* nothing was in the way */ } }
+    };
+    // Whether anything is at the path, the link itself counting rather than what it points at.
+    const there = rel => { try { fs.lstatSync(at(rel)); return true; } catch { return false; } };
+    // The rename is the filesystem's, but its record is Git's: moving a committed folder leaves the
+    // index recording the old path, and no amount of writing to disk corrects that. The same reason
+    // `mark` below goes through Git rather than chmod -- the disk cannot say it. Staged only when
+    // the source was committed, which is the only case where the index now contradicts the disk: a
+    // path nothing tracked leaves nothing to correct, so a repository mid-edit keeps its index, and
+    // a root with no index at all has nothing to keep in step.
+    const stage = e => {
+        const tracked = repoView.indexModes(root, [e.move]);
+        if (!tracked || !tracked.length) return null;
+        // The destination on its own and first. Given both paths at once, `git add` stages the
+        // source's deletion and then fails on the destination -- a target whose .gitignore covers
+        // where the harness keeps its skills is enough -- which leaves the index recording the skill
+        // at neither path while the disk holds it at the new one. So the destination is offered
+        // alone, and if Git will not have it the rename goes back and the index is untouched: the
+        // refusal a real target actually produces costs the repository nothing.
+        const added = git(root, ["add", "-A", "--", e.file]);
+        if (added.status !== 0) {
+            try { fs.renameSync(at(e.file), at(e.move)); }
+            catch { /* the way back is gone too; the message below is all there is to give */ }
+            return cannotStage(e, added);
+        }
+        // Dropping the source afterwards is judged by the index, not by what `git add` answers. A
+        // source now covered by the target's .gitignore is refused and dropped in the same breath:
+        // the command exits non-zero over the ignore rule and takes the entry out of the index all
+        // the same, which is the staging that was asked for. So the index is read back, and only a
+        // read that returns and finds nothing says the move is staged: a read that fails says
+        // nothing, and leaves the refusal standing, which is the safe way round. Nothing rolls back
+        // here and nothing should, the destination being staged by then -- putting the file back on
+        // disk would leave the two contradicting each other rather than as they started.
+        const dropped = git(root, ["add", "-A", "--", e.move]);
+        if (dropped.status === 0) return null;
+        const stillTracked = repoView.indexModes(root, [e.move]);
+        return stillTracked && !stillTracked.length ? null : cannotStage(e, dropped);
+    };
     const marked = [];
     // Git runs a hook only if it is executable and says nothing when it is not, so an installed
     // harness whose hooks are 644 looks installed and gates nothing. The upstream records them
@@ -111,16 +228,50 @@ function worktreeEdit(root) {
     const alreadyExec = file => (repoView.indexModes(root, [file]) || []).some(r => r.file === file && r.exec);
     return {
         ...editing({
-            write: e => { parent(e.file); fs.writeFileSync(at(e.file), e.write); return null; },
-            mkdir: e => { fs.mkdirSync(at(e.file), { recursive: true }); return null; },
+            // Both inside a try, for the same reason the move below is: a project with a folder
+            // where a file goes, or a file where a folder goes, would otherwise take the whole
+            // install down mid-way through with a throw out of `apply`. A refusal is this module's
+            // contract, and it has to hold for the paths the harness writes as well.
+            write: e => {
+                try { parent(e.file); fs.writeFileSync(at(e.file), e.write); }
+                catch (err) { return `could not write ${e.file}: ${err.code || err.message}`; }
+                return null;
+            },
+            mkdir: e => {
+                try { fs.mkdirSync(at(e.file), { recursive: true }); }
+                catch (err) { return `could not create the folder ${e.file}: ${err.code || err.message}`; }
+                return null;
+            },
+            // Git is not asked to do the rename: a skill being adopted is usually untracked, and
+            // `git mv` refuses that. Nothing is overwritten, so a name already taken at the
+            // destination is a refusal rather than a project's work quietly replaced. Asked with
+            // lstat rather than existsSync, because a dangling symlink is something in the way and
+            // exists() follows the link and reports the path free -- and because the map adapter,
+            // holding a link as an entry like any other, answers that question the same way.
+            move: e => {
+                if (!there(e.move)) return noSource(e);
+                if (there(e.file)) return taken(e);
+                // Inside the try with the rename, unlike the writes above: those go to the harness's
+                // own paths, while a move's destination is made under whatever the project already
+                // has there. A repository with a file where .agents/skills should be would take the
+                // whole install down mid-way through, and a refusal is this module's contract.
+                try {
+                    parent(e.file);
+                    fs.renameSync(at(e.move), at(e.file));
+                }
+                catch (err) { return `could not move ${e.move} to ${e.file}: ${err.code || err.message}`; }
+                return stage(e);
+            },
             link: e => {
-                parent(e.file);
+                // Before `clear`, so a parent that cannot be made refuses with the path still as it
+                // was rather than with its way already cleared for a link that never arrives.
+                try { parent(e.file); } catch (err) { return noLink(e, err.code || err.message); }
                 clear(e.file);
                 // Windows needs Developer Mode and core.symlinks=true for this to work at all, so a
                 // refusal is a result rather than a throw: the harness still functions with the link
                 // missing, it is just invisible to the agent harnesses that read it.
                 try { fs.symlinkSync(e.link.split("/").join(path.sep), at(e.file), "dir"); }
-                catch (err) { return `could not create the symlink ${e.file} -> ${e.link}: ${err.code || err.message}`; }
+                catch (err) { return noLink(e, err.code || err.message); }
                 return null;
             },
             mark: e => {
@@ -137,4 +288,8 @@ function worktreeEdit(root) {
     };
 }
 
-module.exports = { worktreeEdit, mapEdit };
+// `kindOf` is exported for the plan's entries, which are built to be read by it: one name per kind
+// across the two, checked rather than kept in step by hand. It covers the four an install plan
+// builds; `move` is relink's alone, and relink assembles its entries directly rather than
+// through `scripts/plan-entry.js`.
+module.exports = { worktreeEdit, mapEdit, kindOf: work };

package/scripts/update-harness.js

@@ -36,6 +36,7 @@ const projectFacts = require("./project-facts");
 const repoView = require("./repo-view");
 const repoEdit = require("./repo-edit");
 const installPolicy = require("./install-policy");
+const entry = require("./plan-entry");
 
 const TEMPLATE = "https://github.com/salaros/ai-harness.git";
 const LOCK = "harness-lock.json";
@@ -126,6 +127,11 @@ function targetRoot(options) {
 
 // ---------------------------------------------------------------- the upstream
 
+// The command line that clone runs on, which is how every install begins that did not bring its own
+// checkout. Separate from the running of it because nothing in the suite clones: a check can read
+// arguments, and cannot watch a network call it must not make.
+const cloneArgs = (ref, dir) => ["-c", "core.longpaths=true", "clone", "--quiet", "--branch", ref, TEMPLATE, dir];
+
 // 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, options) {
@@ -141,7 +147,7 @@ function templateCheckout(ref, options) {
     }
     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]);
+    const r = lib.run("git", cloneArgs(ref, dir));
     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 });
@@ -329,6 +335,10 @@ function skeletonLines(file, lines, hasIntent) {
 
 // git merge-file writes the merged result and reports the number of conflicts, or a negative status
 // for trouble. Used rather than a hand-rolled diff3 because the target already needs Git.
+// This is the one thing a policy decision does that reaches outside the process: it makes a temp
+// directory and spawns Git, which is why the otherwise in-memory decision table touches real disk.
+// That is deliberate, and ADR-0002 is why: a seam here would run the table against a stand-in for
+// diff3, and what diff3 really does to a conflict is the only thing worth checking.
 function threeWay(base, ours, theirs) {
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), "merge-"));
     const f = n => path.join(dir, n);
@@ -367,16 +377,9 @@ function settleDropped(text) {
 // 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 SKILLS = ".agents/skills/";
-
+// one path, and what an entry may be is scripts/plan-entry.js: written, linked, marked, folder,
+// noted or heading, each reported by shown(...) or quiet(...). Nothing here builds an entry by hand,
+// so the rules are the ones that module enforces rather than the ones this comment used to list.
 // `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 = {} }) {
@@ -420,27 +423,35 @@ function plan({ upstream, target, rows, head, ref, previous, options, stamp = {}
     // the mode column says.
     const files = atHead.modes();
     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, mode: m } = entry;
+    add(entry.heading(`${files.length} path(s) in ${ref} at ${head.slice(0, 8)}`));
+    for (const row of files) {
+        const { file, link: isLink, exec, mode: m } = row;
         const { policy, asked } = installPolicy.policyFor(rows, file, options.wants);
         const theirs = contentOf(atHead, 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; }
+        if (theirs === null) { add(entry.noted(file, entry.shown(policy, m, "UNREADABLE", "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) });
-
+        const line = (outcome, bucket, act = {}, silent = false) => {
+            // The upstream's own files are counted and never printed: sixty of them are the suite's
+            // fixtures, and the rule is worth a sentence in the summary rather than sixty lines.
+            const as = silent ? entry.quiet(bucket) : entry.shown(policy, m, outcome, bucket);
+            if (act.link !== undefined) return add(entry.linked(file, act.link, as, { replace: !!act.replace }));
+            const bit = exec && (exists || act.write !== undefined);
+            if (act.write !== undefined) return add(entry.written(file, act.write, as, { exec: bit }));
+            return add(bit ? entry.marked(file, as) : entry.noted(file, as));
+        };
+
+        // Skills are decided for the folder rather than for the path: a skill merges by name, and
+        // one line of output stands for its several hundred files. Collected here and handed to the
+        // seam below, links and all, so this loop leaks around its own policy seam nowhere.
+        if (policy === "skills") { skills.push(row); continue; }
         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; }
             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
@@ -452,10 +463,7 @@ function plan({ upstream, target, rows, head, ref, previous, options, stamp = {}
             else line("merged", "merged", { link: to, replace: true });
             continue;
         }
-        // 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; }
-        const { outcome, bucket, notice, ...act } = installPolicy.decide(policy,
+        const { outcome, bucket, notice, silent, ...act } = installPolicy.decide(policy,
             { exists, theirs, hasBase: base !== null, adopt: options.adopt, asked }, {
                 held: () => Buffer.isBuffer(theirs) ? target.bytes(file) : target.read(file),
                 base: () => contentOf(upstream.at(base), file),
@@ -466,10 +474,10 @@ function plan({ upstream, target, rows, head, ref, previous, options, stamp = {}
                 merge: threeWay,
             });
         if (notice) notices.push(`${file}: ${notice}`);
-        line(outcome, bucket, act);
+        line(outcome, bucket, act, silent);
     }
 
-    add({ phase: "skeletons a project starts with" });
+    add(entry.heading("skeletons a project starts with"));
     const hasIntent = target.exists(projectFacts.INTENT);
     // The receipt lists the skeletons its run knew, so one missing on an update is one the project
     // deleted, and it stays deleted; a skeleton added since still arrives. A receipt from before the
@@ -477,74 +485,29 @@ function plan({ upstream, target, rows, head, ref, previous, options, stamp = {}
     const known = new Set(previous && base !== null ? previous.skeletons || Object.keys(SKELETONS) : []);
     for (const [file, lines] of Object.entries(SKELETONS)) {
         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 });
+        const { outcome, bucket, write } = installPolicy.decide("skeleton",
+            { exists: target.exists(file), theirs, asked: false }, { shippedBefore: () => known.has(file) });
+        const as = entry.shown("seed", "100644", outcome, bucket);
+        add(write === undefined ? entry.noted(file, as) : entry.written(file, write, as));
     }
 
-    add({ phase: "skills, merged by name" });
-    entries.push(...planSkills(atHead, target, skills));
+    add(entry.heading("skills, merged by name"));
+    // Everything the roster is decided from, read through the two views the run already holds: the
+    // policy reads nothing itself, as it reads nothing for one path.
+    entries.push(...installPolicy.decideRoster("skills", skills, {
+        exists: file => target.exists(file),
+        theirs: file => contentOf(atHead, file),
+        held: file => (target.isFile(file) ? target.bytes(file) : null),
+    }));
 
     // 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" });
+    add(entry.written(LOCK, receipt + "\n", entry.quiet()));
     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 planSkills(atHead, target, files) {
-    const LOCKFILE = "skills-lock.json";
-    const theirLock = JSON.parse(atHead.read(LOCKFILE) || '{"skills":{}}');
-    const ourLock = target.isFile(LOCKFILE) ? JSON.parse(target.read(LOCKFILE)) : { skills: {} };
-    ourLock.skills = ourLock.skills || {};
-    const mine = new Set(Object.keys(ourLock.skills));
-
-    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, 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 = contentOf(atHead, file);
-        if (text === null) continue;
-        // 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 ? target.bytes(file) : null;
-        let write;
-        if (Buffer.isBuffer(text)) {
-            if (lib.sameContent(held, text)) continue;
-            write = text;
-        } else {
-            const ourText = held === null ? null : held.toString("utf8");
-            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 });
-    }
-    for (const [name, t] of [...outcomes].sort()) {
-        const what = t.yours ? "yours" : t.added ? "added" : t.updated ? "updated" : "unchanged";
-        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;
-    }
-    out.push({ file: LOCKFILE, silent: true, write: JSON.stringify(ourLock, null, 2) + "\n" });
-    return out;
-}
-
 // ---------------------------------------------------------------- applying it
 
 // An install rewrites someone else's repository, so it says what it did to every path while it does
@@ -552,30 +515,31 @@ function planSkills(atHead, target, files) {
 // 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.
 //
-// The writing is scripts/repo-edit.js, an entry at a time: the line for a path is printed as the
-// path is written, and an edit handed the whole plan at once would leave a long install silent and
-// then print all of it at the end. What order the work inside an entry goes in -- the parent folder
-// before the file, the link's way cleared before the link, the mode after the content -- is the
-// edit's, so this loop takes the plan's order as given and adds nothing to it.
+// The writing is the repo-edit the run was handed, an entry at a time: the line for a path is said
+// as the path is written, and an edit given the whole plan at once would leave a long install silent
+// and then say all of it at the end. What order the work inside an entry goes in -- the parent
+// folder before the file, the link's way cleared before the link, the mode after the content -- is
+// the edit's, so this loop takes the plan's order as given and adds nothing to it. `out` is where a
+// line goes as it happens; the run collects them, and only the command line prints.
 // Returns the entries as they turned out, which the summary is built from.
-function apply(entries, root, options) {
+function apply(entries, edit, options, out = say) {
     const done = [];
-    const edit = repoEdit.worktreeEdit(root);
     for (const e of entries) {
-        if (e.phase) { if (!options.quiet) say(`\n${e.phase}`); continue; }
-        let shown = e;
+        if (e.phase) { if (!options.quiet) out(`\n${e.phase}`); continue; }
+        let actual = e;
         if (!options.dryRun) {
             const [result] = edit.apply([e]);
             // The edit reports; the policy decides. A symlink this platform will not make means the
             // target keeps whatever it already had, which is an outcome word and therefore this
             // run's to choose -- the edit says only that the link is not there and why.
             if (result && !result.done) {
-                say(result.why);
-                if (result.kind === "link") shown = { ...e, outcome: "yours", bucket: "kept" };
+                out(result.why);
+                if (result.kind === "link") actual = entry.turnedOut(e, "yours", "kept");
             }
         }
-        if (!shown.silent && !options.quiet) say(`  ${shown.policy.padEnd(9)}${shown.mode}  ${shown.outcome.padEnd(12)}${shown.file}`);
-        done.push(shown);
+        const line = entry.describe(actual);
+        if (line && !options.quiet) out(line);
+        done.push(actual);
     }
     return done;
 }
@@ -590,17 +554,19 @@ function apply(entries, root, options) {
 // 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.
+// link and describe that repo instead.
+//   { hooks, lines }: whether the hooks were wired, and what the three steps had to say
 function finish(target, options) {
-    if (!options.quiet) say("\nGit hooks, links and notices");
+    const lines = [];
+    if (!options.quiet) lines.push("\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}`);
+        lines.push(r.status === 0 ? r.output : `${label}: ${r.output}`);
         if (label === "git hooks" && r.status !== 0) hooks = false;
     }
-    return hooks;
+    return { hooks, lines };
 }
 
 // Merging is not checking. The installer knows it wrote a file; it cannot know whether the result
@@ -612,22 +578,61 @@ function finish(target, options) {
 // 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.
+//   { check, lines }: what the invariants made of the target, and what running them had to say
 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");
+    if (!fs.existsSync(script)) return { check: { skipped: "this upstream ref has no scripts/check-harness.js" }, lines: [] };
+    const lines = options.quiet ? [] : ["\nself check: the harness invariants, run from the upstream against this repo"];
     const harness = require(script);
     // The root rather than a view of it: this is the upstream's copy of check-harness, at whichever
     // ref the run is installing, and a ref old enough to predate the view still expects a path.
     const r = harness.check(target);
-    return { failed: r.failed.length > 0, summary: r.summary, output: harness.format(r) };
+    return { check: { failed: r.failed.length > 0, summary: r.summary, output: harness.format(r) }, lines };
+}
+
+// The two steps above, which are the only ones that reach outside this process: three scripts
+// spawned in the target, and the upstream's own invariants required out of its checkout and run
+// against it. Behind one adapter, because a run that wants to know what it would do has no target to
+// spawn in and no checkout to require from -- and because every ordering fix this installer has
+// needed landed in exactly these two steps, where nothing short of a real install could reach them.
+//   wire(root, options)            -> { hooks, lines }
+//   invariants(root, upstreamDir, options) -> { check, lines }
+const onDisk = { wire: finish, invariants: selfCheck };
+
+// Which paths joined which summary list. The lists are install-policy's to name: it is where a
+// bucket is decided, and a second copy of the names here is a second place to forget one.
+const bucketed = entries => {
+    const notes = Object.fromEntries(installPolicy.BUCKETS.map(b => [b, []]));
+    for (const e of entries) if (e.bucket) (notes[e.bucket] || []).push(e.file);
+    return notes;
+};
+
+// Whether the run left anything for the reader to act on, and what. The one place that knows what
+// makes an install fail: it used to be a single expression at the foot of the printer below, so the
+// only way to ask was to run the install and read its stdout. Every reason is named, not the first
+// one found -- a run with conflicts and unwired hooks has two things wrong with it.
+function verdict({ entries, check, hooks = true }) {
+    const notes = bucketed(entries);
+    const why = [];
+    for (const bucket of installPolicy.UNFINISHED) {
+        const n = notes[bucket].length;
+        if (n) why.push(bucket === "conflicted"
+            ? `${n} path(s) hold conflict markers to resolve by hand`
+            : `${n} path(s) could not be read out of the upstream checkout, so they are not installed`);
+    }
+    if (check && check.failed) why.push("the harness's own checks do not pass in the target");
+    if (!hooks) why.push("the target's Git hooks are not wired, so nothing gates a commit there");
+    return { failed: why.length > 0, why };
 }
 
-// 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, 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);
+// The summary in words, as lines: what happened, then whatever the verdict says is outstanding.
+// Returned rather than printed, so what a run reports can be read by a check the way a reader reads
+// it. The verdict is read here and never worked out again -- two answers to "did this run fail?"
+// drift, and the one CI reads is the one nobody is looking at.
+function summarise({ entries, base, head, ref, target, check, hooks = true, options }) {
+    const notes = bucketed(entries);
+    const out = [];
+    const say = line => out.push(line);
     // 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.
@@ -666,7 +671,7 @@ function report({ entries, base, head, ref, target, check, hooks = true, options
     // 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;
+    return out;
 }
 
 // ---------------------------------------------------------------- the run
@@ -678,6 +683,68 @@ function upToDate(previous, head, options, optional) {
     return !!previous && previous.commit === head && !options.adopt && !optional.some(name => options.wants(name));
 }
 
+// The parts of the harness a project has to ask for by name, as the manifest names them.
+const optionalParts = rows => rows.filter(r => r.policy.startsWith("optional:")).map(r => r.policy.slice("optional:".length));
+
+// One install, end to end, as a value. It decides whether there is anything to do, plans it, applies
+// the plan through the target's repo-edit, takes the two steps that reach outside this process, and
+// works out what it all came to -- and it returns every one of those rather than printing any of
+// them. Which is the whole point: two-thirds of this file used to be reachable only by spawning the
+// installer at somebody's repository, so an ordering question could be asked only of stdout after an
+// eighteen-second install, and was therefore asked only after it had already gone wrong.
+//
+// `say` is where a line goes the moment it is produced, and defaults to nowhere. An install rewrites
+// someone else's repository and has to narrate itself while it does it, so the lines cannot simply
+// be handed over at the end; collecting them and passing them on at once is the same list either
+// way, which is why a check can assert on what a run said without watching a terminal.
+//   upstream { view, rows, head, ref, dir }   the upstream side, already checked out and read
+//   target   { view, edit, root, previous }   the target side: what to read, what to write through
+//   options, stamp                            the parsed command line, and what the receipt records
+//   after                                     the steps outside this process; see onDisk above
+//   -> { entries, notices, lines, base, head, ref, target, check, hooks, options, verdict }
+function run({ upstream, target, options, stamp = {}, after = onDisk, say: out = () => {} }) {
+    const lines = [];
+    const said = line => { lines.push(line); out(line); };
+
+    if (upToDate(target.previous, upstream.head, options, optionalParts(upstream.rows))) {
+        said(`harness is already at ${upstream.head.slice(0, 8)} (${upstream.ref}); nothing to update`);
+        return { entries: [], notices: [], lines, base: null, head: upstream.head, ref: upstream.ref,
+            target: target.root, check: null, hooks: true, options, verdict: { failed: false, why: [] } };
+    }
+
+    const planned = plan({
+        upstream: upstream.view, target: target.view, rows: upstream.rows,
+        head: upstream.head, ref: upstream.ref, previous: target.previous, options, stamp,
+    });
+    for (const notice of planned.notices) said(notice);
+    const entries = apply(planned.entries, target.edit, options, said);
+
+    let check = null;
+    let hooks = true;
+    // After the plan is applied, because relink needs the skills in place and the invariants check
+    // the links relink has just written. A dry run wrote nothing, so there is nothing to wire or
+    // check and both steps are the target's own business until it is installed for real.
+    if (!options.dryRun) {
+        const wired = after.wire(target.root, options);
+        hooks = wired.hooks;
+        for (const line of wired.lines) said(line);
+        if (options.check) {
+            const ran = after.invariants(target.root, upstream.dir, options);
+            check = ran.check;
+            for (const line of ran.lines) said(line);
+        }
+    }
+
+    const result = { entries, notices: planned.notices, base: planned.base, head: upstream.head,
+        ref: upstream.ref, target: target.root, check, hooks, options };
+    for (const line of summarise(result)) said(line);
+    return { ...result, lines, verdict: verdict(result) };
+}
+
+// The command line: the one adapter over the run above. It works out which upstream and which target
+// the arguments mean, clones if it has to, prints every line the run says as the run says it, and
+// turns the verdict into the exit code npx and CI read. Nothing here decides anything about an
+// install; everything it decides is about the process it is running in.
 // Returns the exit code, and throws Stop for a run that could not start.
 function main(args) {
     const options = parseOptions(args);
@@ -698,39 +765,29 @@ function main(args) {
     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);
+        const unknown = unknownArgs(args, optionalParts(rows));
         if (unknown.length) fail(`unknown argument(s): ${unknown.join(" ")}. Nothing was written; run with --help for the options.`);
         const head = git(templateDir, ["rev-parse", "HEAD"]).output.trim();
-        if (upToDate(previous, head, options, optional)) {
-            say(`harness is already at ${head.slice(0, 8)} (${ref}); nothing to update`);
-            return 0;
-        }
 
-        const planned = plan({
-            upstream: gitUpstream(templateDir), target: here, rows, head, ref, previous, options,
+        const result = run({
+            upstream: { view: gitUpstream(templateDir), rows, head, ref, dir: templateDir },
+            target: { view: here, edit: repoEdit.worktreeEdit(target), root: target, previous },
+            options,
             stamp: { ...installer(), updated: new Date().toISOString().slice(0, 10) },
+            say,
         });
-        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.
-            hooks = finish(target, options);
-            if (options.check) check = selfCheck(target, templateDir, options);
-        }
-        return report({ entries, base: planned.base, head, ref, target, check, hooks, options });
+        return result.verdict.failed ? 1 : 0;
     } 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 = { installerStamp, upToDate, settleDropped, unknownArgs, mistypedArgs, usage, parseOptions, plan, apply, lineCounts, overlap, NEAREST, skeletonLines };
+// run() is the interface: a whole install as a value, against whatever upstream, target and steps
+// the caller hands it. The rest are the decisions under it, exported so a case can go in and an
+// answer come out without a git checkout to reach one branch of one of them. main() is not among
+// them: it is the command line, it writes to somebody's repository, and it is reached by running
+// this file.
+module.exports = { run, cloneArgs, installerStamp, upToDate, settleDropped, unknownArgs, mistypedArgs, usage, parseOptions, plan, apply, verdict, summarise, lineCounts, overlap, NEAREST, skeletonLines };
 
 if (require.main === module) {
     try { process.exitCode = main(process.argv.slice(2)); }