@salaros/ai-harness 0.1.0 → 0.2.1

package/README.md

@@ -26,6 +26,10 @@ Running it again updates. The first run writes `harness-lock.json` naming the up
 
 Skills are added and updated, never removed: one you vendored yourself survives every update, and `skills-lock.json` is merged as a union.
 
+A repo whose harness predates `harness-lock.json` is the one case where "never touch what is already there" works against you: with no receipt there is no merge base, so the old harness stays and its checks then run against the new skills and fail, naming rules this version dropped. The run says so and names `--adopt`, which replaces every harness file with the upstream's — hooks, agents, scripts, `AGENTS.md`, and a `.claude/agents` that checked out as a text file rather than a symlink. It stays opt-in because it discards your edits to those files. `--dry-run --quiet` lists them first.
+
+The run reports each path as it works on it: the policy, the mode Git records, what happened, and the path, with the skills tree collapsed to one line per skill. `--quiet` gives the summary alone.
+
 ## Getting started
 
 1. **Windows only, before cloning:** enable Developer Mode (Settings → System → For developers) and run `git config --global core.symlinks true`. The `.claude/` folder is tracked as symlinks; without this, Git checks them out as text files and Claude Code sees no skills.
@@ -41,14 +45,14 @@ Skills are added and updated, never removed: one you vendored yourself survives
 | `src/`, `tests/`, `scripts/`, `tools/`, `docs/` | Product code, tests, repo automation, dev utilities, documents. Each has a README describing what belongs there. |
 | `AGENTS.md` | The one file every agent reads: layout, where skills are, domain-language pointers. Kept short on purpose. |
 | `CLAUDE.md` | One line, `@AGENTS.md`, because Claude Code reads `CLAUDE.md` rather than `AGENTS.md`. |
-| `MEMORY.md` | The project facts (name, purpose, requirements location, stack, the frontend framework when the project has browser code, and the issue tracker when there is one), one per line. Written by the `project-init` skill; absent until it runs. |
+| `MEMORY.md` | The project facts (name, purpose, the language its prose is written in, requirements location, stack, the frontend framework when the project has browser code, and the issue tracker when there is one), one per line. Written by the `project-init` skill; absent until it runs. |
 | `TODO.md` | The loose-ends ledger: questions nobody has answered, assumptions taken on trust, and work knowingly left undone. Follows the [todo-md standard](https://github.com/todo-md/todo-md) -- a `# TODO` header, one entry per line as `- [ ] <text> #<tag> (<source>)`, `@user` and indented subtasks optional -- so its tooling reads this file. Written by the `loose-ends` skill and absent until the first entry, since an empty ledger says less than no ledger. It departs from the standard in one place: a settled entry is deleted in the commit that settles it rather than kept as `[x]` or `[-]`, because entries nobody will act on are context every agent re-reads. Needs no issue tracker. |
 | `THIRD-PARTY-NOTICES.md`, `scripts/skill-licences.tsv` | Vendoring a skill copies someone else’s work here, and MIT and Apache-2.0 both ask that the copyright and permission notice travel with the copy; `npx skills` carries only what sits inside the skill folder, so an upstream keeping its licence at the repo root sends none. The TSV holds one row per upstream (SPDX id, copyright line, licence URL, and any restriction); `node scripts/skills.js notices` regenerates the notice from it and `skills-lock.json`. A new upstream with no row fails the harness suite. |
 | `skills-lock.json` | Written by `npx skills`: source, path and hash of every installed skill. The single record of what is installed; `node scripts/skills.js install` restores from it. |
 | `.agents/skills/<name>/` | The canonical, vendored copy of each skill (`SKILL.md` plus its reference files). |
 | `.agents/hooks/` | Harness-neutral hook scripts (see [Hooks](#hooks)). |
 | `.agents/agents/` | Agent definitions (see [Agents](#agents)). |
-| `scripts/update-harness.js`, `scripts/harness-files.tsv`, `harness-lock.json` | The installer, the table of what travels and what does not, and the receipt naming the upstream commit a repo last took. The first two are the upstream’s own and are never installed; the receipt is written into the repo being updated. |
+| `scripts/update-harness.js`, `scripts/harness-files.tsv`, `harness-lock.json` | The installer, the table of what travels and what does not, and the receipt naming the upstream commit a repo last took and the released installer that wrote it. The first two are the upstream’s own and are never installed; the receipt is written into the repo being updated. |
 | `.agents/routing.md` | Route rows shared by some agents but not all, in a section per audience, plus the rule for what earns a row. What every agent needs is in `AGENTS.md` ("Working here") instead, since every session loads that. Above `agents/` because `.claude/agents` is a symlink to that folder and a harness reads everything in it as an agent. |
 | `.claude/` | Claude Code wiring: `skills/*` and `agents` are symlinks into `.agents/`, `settings.json` wires the hooks. |
 | `.githooks/`, `scripts/githooks-init.js` | Git hooks, run through `core.hooksPath` after `githooks-init.js` is run once per clone. They are the only shell scripts left, because Git runs them through its own `sh` on every OS; each is a two-line wrapper piping changed paths into a Node script. `post-merge` feeds `scripts/on-manifest-change.js`, which restores what `scripts/stacks.tsv` says (skills, npm, pnpm, yarn, NuGet, uv). `pre-commit` and `pre-push` both start with `scripts/check-initialised.js`, which refuses an unconfigured clone: `MEMORY.md` must record the six facts that describe the project itself (name, purpose, requirements, unit type, language, runtime), none of them left as a `<placeholder>`. The `Jira` line is not among them: a tracker is a choice, not a property of the code. `pre-commit` then pipes the staged `TODO.md` into `scripts/check-todo.js`, which checks the shape of the loose-ends ledger against the todo-md standard: the `# TODO` header, and an entry carrying a known tag (`#question`, `#assumption`, `#deferred`) and a source the chain would accept. Only checkbox lines are entries, every other line is prose, and an indented subtask inherits its parent's tag and source. It never asks for entries to exist, and it rejects `[x]` and `[-]`, because a settled entry is deleted rather than kept. `pre-commit` then feeds `scripts/check-staged-docs.js`, which blocks a commit that would break the documentation chain. `commit-msg` feeds `scripts/check-commit-msg.js`, which blocks a commit whose message is not a conventional commit (`<type>(<scope>)?!?: <description>`, subject at most 72 characters, a description of at least four words, and a body of real prose after a blank line — trailers such as `Refs:` are metadata and do not count as one); messages Git writes itself for a merge, revert, fixup or squash are left alone. A message citing no Jira issue key is warned about rather than rejected, to encourage the habit without blocking a change nobody has raised a ticket for; the key comes from `docs/agents/issue-tracker.md`, and any `PROJ-123` shape counts until `project-init` records the real one. A project whose `MEMORY.md` records `Issue tracker: none` is not warned: it has no key to cite. A tracker whose references are not `KEY-123` sets `Key format:` in `docs/agents/issue-tracker.md`, so a GitHub-Issues project is warned about `#42` instead. `pre-push` feeds `scripts/format-changed.js`, which checks that the files a push publishes are formatted, using the stack's own formatter from `scripts/stacks.tsv` (`prettier`, `dotnet format` or a project's Husky.NET task runner, `ruff`). It never rewrites files: it reports and blocks, and skips silently when the stack's formatter is not installed. Formatting is checked on push rather than on commit because some formatters load the whole project and cost seconds. The restore, chain and format scripts take `--dry-run`; `check-commit-msg.js` takes the message file, or reads stdin. `git commit --no-verify` and `git push --no-verify` skip them. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salaros/ai-harness",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "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"

package/scripts/update-harness.js

@@ -22,6 +22,8 @@
 //   node scripts/update-harness.js --from ../ai-harness use a checkout you already have, no clone
 //   node scripts/update-harness.js --astro-docs        add tools/docs-site, the Astro renderer for the chain
 //   node scripts/update-harness.js --no-check          install without proving it afterwards
+//   node scripts/update-harness.js --quiet             the summary alone, no line per path
+//   node scripts/update-harness.js --adopt             replace a harness that predates harness-lock.json
 // Installing into a repo that has no harness yet, from anywhere:
 //   git clone https://github.com/salaros/ai-harness .harness && \
 //     node .harness/scripts/update-harness.js --from .harness --target . && rm -rf .harness
@@ -39,6 +41,7 @@ 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; };
 const dryRun = flag("--dry-run");
+const adopt = flag("--adopt");
 
 // ---------------------------------------------------------------- the target
 
@@ -80,6 +83,19 @@ function templateCheckout(ref) {
     return { dir, temporary: true };
 }
 
+// The installer's own name and version, read from the package it ships inside rather than written
+// down here, so a release cannot forget to update it. It answers what the upstream commit cannot:
+// which released tool wrote this tree. Both routes land on the right file, because the script always
+// sits in the scripts/ folder of either the npm package or a checkout of the upstream. Omitted
+// rather than recorded as null when it cannot be read, so the receipt never claims a version it
+// does not know.
+function installer() {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, "..", "package.json"), "utf8"));
+        return pkg.name && pkg.version ? { installer: `${pkg.name}@${pkg.version}` } : {};
+    } catch { return {}; }
+}
+
 const at = (dir, args) => lib.run("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
@@ -142,9 +158,12 @@ function link(target, file, to) {
     let existing = null;
     try { existing = fs.lstatSync(full); } catch { /* absent */ }
     if (existing) {
-        if (!existing.isSymbolicLink()) return "kept";       // something of the project's is in the way
-        if (fs.readlinkSync(full).split(path.sep).join("/") === to) return null;
-        fs.unlinkSync(full);
+        // 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");
@@ -173,6 +192,7 @@ const SKELETONS = {
         "",
         "- **Name:** <name>",
         "- **Purpose:** <purpose>",
+        "- **Prose language:** <prose language>",
         "- **Requirements:** <requirements>",
         "- **Unit type:** <unit type>",
         "- **Language:** <language>",
@@ -199,9 +219,9 @@ const SKELETONS = {
 
 function skeletons(target) {
     for (const [file, lines] of Object.entries(SKELETONS)) {
-        if (fs.existsSync(path.join(target, file))) continue;
+        if (fs.existsSync(path.join(target, file))) { step("seed", "100644", "yours", file); continue; }
         write(target, file, lines.join("\n"));
-        notes.seeded.push(file);
+        step("seed", "100644", "created", file, "seeded");
     }
 }
 
@@ -228,6 +248,19 @@ const notes = { written: [], merged: [], conflicted: [], seeded: [], kept: [], s
 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}`); };
+
 function write(target, file, text, exec) {
     const full = path.join(target, file);
     if (dryRun) return;
@@ -263,6 +296,7 @@ function selfCheck(target, templateDir, head, files) {
         write(target, file, text);
         borrowed.push(file);
     }
+    phase(`self check: ${borrowed.length} file(s) borrowed from the upstream suite`);
     if (!borrowed.length) return { skipped: "the suite is already in this repo; run it yourself with node .agents/hooks/test.js" };
 
     try {
@@ -300,17 +334,34 @@ function main() {
         }
         if (previous && base === head) { say(`harness is already at ${head.slice(0, 8)} (${ref}); nothing to update`); return; }
 
+        // 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 rows = policies(templateDir);
         const files = templateFiles(templateDir);
         const skills = [];
 
-        for (const { file, link: isLink, exec } of files) {
+        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);
+            const m = mode(entry);
             const theirs = blob(templateDir, head, file);
             if (theirs === null) continue;
             const full = path.join(target, file);
             const exists = fs.existsSync(full);
 
+            // 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
@@ -320,40 +371,51 @@ function main() {
                     continue;
                 }
                 const how = link(target, file, theirs.trim());
-                if (how) notes[how].push(file);
+                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") { if (exists) notes.skipped.push(file); continue; }
+            if (policy === "skip") { step(policy, m, exists ? "yours" : "absent", file, exists && "skipped"); continue; }
 
             if (policy === "seed") {
-                if (exists) { notes.kept.push(file); continue; }
+                if (exists) { step(policy, m, "yours", file, "kept"); continue; }
                 write(target, file, theirs, exec);
-                notes.seeded.push(file);
+                step(policy, m, "created", file, "seeded");
                 continue;
             }
             // merge
-            if (!exists) { write(target, file, theirs, exec); notes.written.push(file); continue; }
+            if (!exists) { write(target, file, theirs, exec); step(policy, m, "written", file, "written"); continue; }
             const ours = fs.readFileSync(full, "utf8");
-            if (ours === theirs) continue;                       // already current
-            if (base === null) { notes.kept.push(file); continue; }
+            if (ours === theirs) { step(policy, m, "unchanged", file); continue; }
+            if (base === null) {
+                if (!adopt) { step(policy, m, "yours, no base", file, "kept"); continue; }
+                write(target, file, theirs, exec);
+                step(policy, m, "adopted", file, "written");
+                continue;
+            }
             const from = blob(templateDir, base, file);
-            if (from === null) { notes.kept.push(file); continue; }   // new to the upstream, and the target has its own
-            if (ours === from) { write(target, file, theirs, exec); notes.written.push(file); continue; }
+            if (from === null) { step(policy, m, "yours, new here", file, "kept"); continue; }
+            if (ours === from) { write(target, file, theirs, exec); step(policy, m, "written", file, "written"); continue; }
             const merged = threeWay(from, ours, theirs);
-            if (merged.failed) { notes.kept.push(file); continue; }
+            if (merged.failed) { step(policy, m, "yours, merge failed", file, "kept"); continue; }
             write(target, file, merged.text, exec);
-            (merged.conflicts ? notes.conflicted : notes.merged).push(file);
+            if (merged.conflicts) step(policy, m, "CONFLICT", file, "conflicted");
+            else step(policy, m, "merged", file, "merged");
         }
 
+        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, updated: new Date().toISOString().slice(0, 10),
+                template: TEMPLATE, ref, commit: head, ...installer(),
+                updated: new Date().toISOString().slice(0, 10),
             }, null, 2) + "\n");
             finish(target);
             // After finish(), because the suite checks the links relink has just written.
@@ -376,18 +438,29 @@ function mergeSkills(target, templateDir, head, files) {
     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 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) {
         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++;
         // A skill the project installed under a name the upstream also uses stays the project's.
-        if (mine.has(name) && !theirLock.skills[name]) continue;
+        if (mine.has(name) && !theirLock.skills[name]) { tally.yours = true; continue; }
         const text = blob(templateDir, head, file);
         if (text === null) continue;
         const full = path.join(target, file);
         const exists = fs.existsSync(full);
         if (exists && fs.readFileSync(full, "utf8") === text) continue;
         write(target, file, text);
-        (exists ? notes.merged : notes.written).push(file);
+        if (exists) { tally.updated++; notes.merged.push(file); }
+        else { tally.added++; notes.written.push(file); }
+    }
+    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))`);
     }
     for (const [name, entry] of Object.entries(theirLock.skills)) {
         if (!ourLock.skills[name]) ourLock.skills[name] = entry;
@@ -400,6 +473,7 @@ function mergeSkills(target, templateDir, head, files) {
 // 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");
     for (const [label, args] of [["links", ["relink"]], ["notices", ["notices"]]]) {
         const r = lib.node([path.join(target, "scripts/skills.js"), ...args], { cwd: target });
         say(r.status === 0 ? r.output : `${label}: ${r.output}`);
@@ -407,7 +481,14 @@ function finish(target) {
 }
 
 function report(target, head, ref, base) {
-    const list = (label, arr) => { if (arr.length) say(`\n${label} (${arr.length}):\n  ${arr.sort().join("\n  ")}`); };
+    // 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  ")}`);
+        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)}`);
     if (!base) say("no merge base: this was an install, so nothing that already existed was changed");
@@ -422,7 +503,7 @@ function report(target, head, ref, base) {
         say(`\nnot installed, the upstream's own (${notes.template.length}): ${named.join(", ")}, and the suite's fixtures`);
     }
     if (notes.conflicted.length) {
-        list("CONFLICTED, resolve the markers by hand", notes.conflicted);
+        list("CONFLICTED, resolve the markers by hand", notes.conflicted, true);
         say(`\nEach one holds <<<<<<< yours / ======= / >>>>>>> upstream (new). Resolve them, then run the suite:\n  node .agents/hooks/test.js`);
     }
     const check = notes.check;