@salaros/ai-harness 0.2.3 → 0.2.7

package/README.md

@@ -2,7 +2,7 @@
 
 A starting point that does not assume a language or framework: `.gitignore`, `.gitattributes`, Git hooks, a folder layout with a README in every folder, and an AI-agnostic **agent harness** (skills, hook scripts, four agents) that works the same in Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and any other tool that reads `AGENTS.md` and `.agents/skills`.
 
-Requires **Node 22 or newer** (the only runtime the harness needs) and Git; nothing else. The [harness CI workflow](.github/workflows/harness.yml) runs the suite on Ubuntu and Windows. A second workflow, [skills-update](.github/workflows/skills-update.yml), runs `npx skills update` weekly, relinks, regenerates the third-party notice, and commits the result to `development` only if the suite and the chain check still pass; it then opens a pull request promoting `development` to `master`, because a skill is a prompt an agent runs with full permissions and its diff wants a reader. A third, [release](.github/workflows/release.yml), publishes this package to npm when a `v*` tag is pushed, over npm trusted publishing rather than a stored token: it proves the tag and `package.json` agree, runs the suite and the chain check, and refuses to publish a tarball missing the installer.
+Requires **Node 22 or newer** (the only runtime the harness needs) and Git; nothing else. The [harness CI workflow](.github/workflows/harness.yml) runs the suite on Ubuntu and Windows. A second workflow, [skills-update](.github/workflows/skills-update.yml), runs `npx skills update` weekly, relinks, regenerates the third-party notice, and commits the result to `development` only if the suite and the chain check still pass; it then opens a pull request promoting `development` to `master`, because a skill is a prompt an agent runs with full permissions and its diff wants a reader. A third, [release](.github/workflows/release.yml), publishes this package to npm when a bare version tag such as `0.2.4` is pushed, over npm trusted publishing rather than a stored token: it runs the suite and the chain check, refuses a tag that is lightweight, disagrees with `package.json` or names a commit that is not on `master`, refuses a tarball missing the installer, and cuts a GitHub Release from a second job that holds no npm credential.
 
 ## Adding the harness to a repository you already have
 
@@ -14,11 +14,13 @@ npx @salaros/ai-harness
 
 It installs what the harness needs and nothing else: `AGENTS.md`, the agents and their routing, the skills, the Git hooks, and the checks those hooks call, the documentation-chain validator among them. What maintains the upstream stays behind — the installer itself, the harness test suite and its fixtures, the CI workflows, `package.json`, and the .NET and OpenCode config a project may have no use for.
 
+The published package is the installer, not the harness. npm carries four files -- `scripts/update-harness.js`, `scripts/lib.js`, `README.md` and `LICENSE` -- and everything they install comes from a clone of this repository, made at run time from the `master` branch. So the version on npm numbers the installer, not what it installs, and two runs of the same version a month apart give you different skills. That is the trade the harness makes: `master` is the released line, reached only through a reviewed pull request, and tracking it lets a skill fix reach every repo the week it lands instead of waiting for a release. What it costs is reproducibility across time. Pass `--ref <tag>` when you need a fixed harness, and read `harness-lock.json` to see the exact commit a past run took.
+
 It never writes `README.md` or `LICENSE`. Under `docs/`, `src/`, `tests/`, `tools/`, `workflows/` and `.scratch/` it adds the folder README where that file is absent and touches nothing else, so a `src/` with code in it gains a README and keeps the code. A first run leaves three skeletons behind when the repo has none: `MEMORY.md` with its six facts still `<placeholder>`, so the initialisation gate says what to run next; an empty `CONTEXT.md` glossary; and a `TODO.md` holding its header and nothing else. Later runs leave all three alone.
 
 Pass `--astro-docs` to also install `tools/docs-site/`, the Astro site that renders the chain in a browser. Nothing in the harness reaches it, so it stays out unless asked for.
 
-Every run proves itself before it finishes. Merging is not checking: the installer knows it wrote a file, not whether the result still works. So it borrows the upstream's own test suite — writes it in, runs it, and takes it away again, leaving the repo as the install left it — and reports what it found. A failure exits non-zero, the same way a conflict does. That is what catches an `AGENTS.md` whose chain table no longer parses, routing sections naming an agent this repo does not have, a skill nothing links to, or a vendored upstream with no licence row. Pass `--no-check` to skip it.
+Every run checks its result before it finishes. Merging is not checking: the installer knows it wrote a file, not whether the result still works. So it runs the harness invariants in `scripts/check-harness.js`, from the upstream checkout against the repo it just wrote, writes nothing to run them, and reports what it found. A failure exits non-zero, the same way a conflict does. That is what catches an `AGENTS.md` whose chain table no longer parses, routing sections naming an agent this repo does not have, a skill nothing links to, or a vendored upstream with no licence row. Pass `--no-check` to skip it.
 
 `scripts/harness-files.tsv` is the table behind all of this, one row per path.
 
@@ -51,7 +53,7 @@ The run reports each path as it works on it: the policy, the mode Git records, w
 | `CLAUDE.md` | One line, `@AGENTS.md`, because Claude Code reads `CLAUDE.md` rather than `AGENTS.md`. |
 | `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. |
+| `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 `node scripts/check-harness.js`. |
 | `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)). |
@@ -59,7 +61,7 @@ The run reports each path as it works on it: the policy, the mode Git records, w
 | `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. |
+| `.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 that finds the repo root and hands over to `scripts/githook.js`, which holds what every hook decides, so nothing is chosen in a file the suite cannot drive. `post-merge` works out what the merge brought in and 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 reads `TODO.md` and checks the shape of the loose-ends ledger against the todo-md standard — the staged copy, whose problems block the commit, or an unstaged one, whose problems are only reported, since the commit does not carry it: 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. |
 | `docs/agents/` | Per-repo configuration the skills read: issue tracker, triage labels, domain-doc rules. |
 | `CODING_STANDARDS.md` | Rules the `code-review` skill applies to a diff. A stub until the stack lands; anything a tool enforces stays out of it. |
 | `.editorconfig`, `.gitattributes`, `.gitignore`, `stylecop.json` | Encoding, indentation, line endings, ignored output and analyzer settings. Stack-specific entries are kept when they are inert on other stacks, so no stack is forced. |
@@ -70,7 +72,7 @@ The run reports each path as it works on it: the policy, the mode Git records, w
 
 ## Skills
 
-Skills follow the Agent Skills format: a folder with a `SKILL.md` whose frontmatter carries a `name` and a `description`, plus optional reference files. They are managed with the [`skills` CLI](https://skills.sh); `skills-lock.json` records what is installed and `.agents/skills` holds the files. Commit both, plus the `.claude/skills` links.
+Skills follow the Agent Skills format: a folder with a `SKILL.md` whose frontmatter carries a `name` and a `description`, plus optional reference files. They are managed with the [`skills` CLI](https://skills.sh); `skills-lock.json` records what is installed and `.agents/skills` holds the files. Commit both, plus the `.claude/skills` link.
 
 ```bash
 npx skills add mattpocock/skills -s wait-what -a claude-code codex -y   # add a skill
@@ -79,11 +81,11 @@ npx skills update                                                  # newer versi
 node scripts/skills.js relink                                      # after any of the above, and after writing a local skill
 ```
 
-- Relink does two things. It creates a `.claude/skills` link for every skill under `.agents/skills` that has none, which is how a local skill written by hand becomes visible to the harness at all: `npx skills` links only what it vendored. And on Windows it rewrites the links the CLI recreates as absolute junctions, which Git cannot store, into relative symlinks. It is idempotent, it reports a link pointing at a skill that is no longer installed, and the test suite fails if any installed skill is unlinked.
+- Relink maintains the harness folders. `.claude/skills` is one link to `.agents/skills`, so every skill there is already visible, a local one written by hand included; relink says so and leaves it alone. Any other harness folder holding a `skills/` directory gets a link per skill instead, which is what makes a hand-written skill visible where `npx skills` links only what it vendored, and on Windows relink rewrites the absolute junctions the CLI creates, which Git cannot store, into relative symlinks. It is idempotent, it reports a link pointing at a skill that is no longer installed, and `node scripts/check-harness.js` fails if a per-skill link is missing or the folder link points anywhere but `.agents/skills`.
 - `node scripts/skills.js install` restores `.agents/skills` from the lock file. A normal clone never needs it; the post-merge Git hook runs it when the lock changes.
 - Do not edit a vendored skill in place; the next update overwrites it. Fork it under another name outside `.agents/skills`, or change it upstream.
 - Two kinds of skill: **model-invoked** ones carry a description the agent matches on its own; **user-invoked** ones (`disable-model-invocation: true`) only fire when you type `/name`.
-- The lock file records only a hash per skill, so an upstream repo going private or rewriting history is otherwise invisible. Run `npx skills update` every so often (monthly, or before a stretch of work that leans on skills), then `node .agents/hooks/test.js` to catch a skill an update broke, and review the diff before committing. The current upstreams are `addyosmani/agent-skills`, `alirezarezvani/claude-skills`, `anthropics/skills`, `codewithmukesh/dotnet-claude-kit`, `dietrichgebert/ponytail`, `diskd-ai/design-doc`, `github/awesome-copilot`, `jeffallan/claude-skills`, `mattpocock/skills`, `mindrally/skills`, `openai/skills`, `softaworks/agent-toolkit`, `sprngr/rubber-duck`, `thebushidocollective/han`, `vercel-labs/agent-browser`, `vercel-labs/agent-skills`, `vercel-labs/skills`, `vuejs-ai/skills`, `wondelai/skills` and `wshobson/agents`.
+- The lock file records only a hash per skill, so an upstream repo going private or rewriting history is otherwise invisible. Run `npx skills update` every so often (monthly, or before a stretch of work that leans on skills), then `node scripts/check-harness.js` to catch a skill an update broke, and review the diff before committing. The current upstreams are `addyosmani/agent-skills`, `alirezarezvani/claude-skills`, `anthropics/skills`, `codewithmukesh/dotnet-claude-kit`, `dietrichgebert/ponytail`, `diskd-ai/design-doc`, `github/awesome-copilot`, `jeffallan/claude-skills`, `mattpocock/skills`, `mindrally/skills`, `openai/skills`, `softaworks/agent-toolkit`, `sprngr/rubber-duck`, `thebushidocollective/han`, `vercel-labs/agent-browser`, `vercel-labs/agent-skills`, `vercel-labs/skills`, `vuejs-ai/skills`, `wondelai/skills` and `wshobson/agents`.
 
 `node scripts/skills.js list` prints what is installed: name, how it is invoked, which agents route it, and where it came from. It is a report, not a rule; nothing requires a skill to be routed or listed anywhere.
 
@@ -95,11 +97,11 @@ Three Node scripts in `.agents/hooks/`, run with the `node` on your PATH (Window
 | --- | --- | --- |
 | `session-start.js` | session start | Prints a brief into the agent's context: branch, whether Git hooks are installed, skills recorded in `skills-lock.json` but missing from disk, whether `CONTEXT.md`, `docs/adr/` and the issue-tracker config exist. |
 | `guard-command.js` | before a shell command | Blocks force pushes, `git reset --hard`, `git clean -f`, `git branch -D`, and recursive deletes of `/`, `~`, `.git` or `*`. Checks the harness's own command field (falling back to the raw payload for an unrecognised shape) and only where the phrase could be a real invocation, so a dangerous phrase quoted as data in another command's arguments does not trip it. The agent is told to ask you instead. |
-| `check-edit.js` | after a file write/edit | Syntax-checks `*.js`, validates `*.json`, runs `scripts/docs-check.js` for Markdown under `docs/` and for `AGENTS.md`, runs the hook suite when the harness itself changed, and refuses in-place edits of vendored skills. |
+| `check-edit.js` | after a file write/edit | Syntax-checks `*.js`, validates `*.json`, runs `scripts/docs-check.js` for Markdown under `docs/` and for `AGENTS.md`, runs `scripts/check-harness.js` when a path its invariants read changed (the skills and their links, the routing, the Git hooks, the licence rows), runs the hook suite in the upstream when harness code or a table changed, and refuses in-place edits of vendored skills. |
 
 The scripts are harness-neutral; the wiring is one small config file per tool, listed under [Files per AI tool](#files-per-ai-tool). Only the Claude Code wiring ships in the repo, because it is the one that has been run.
 
-`lib.js` is the one place that knows how a harness hands over its payload: it finds the repo root (`CLAUDE_PROJECT_DIR`, `CURSOR_PROJECT_DIR` or `GEMINI_PROJECT_DIR`, else the checkout the hooks live in) and turns the edited path into a repo-relative one whether the harness sent `tool_input.file_path` (Claude Code, Gemini CLI), a top-level `file_path` (Cursor) or a `toolArgs` string with a `path` (Copilot). Paths outside the repo and unreadable payloads are skipped with a note on stderr, never blocked. `node .agents/hooks/test.js` pipes every fixture in `.agents/hooks/tests/` through its script (a hook, or `scripts/on-manifest-change.js --dry-run`) and compares exit code and output; `check-edit.js` runs that suite itself whenever a hook, a script the hooks call, the Git hook or the stack table changes.
+`lib.js` is the one place that knows how a harness hands over its payload: it finds the repo root (`CLAUDE_PROJECT_DIR`, `CURSOR_PROJECT_DIR` or `GEMINI_PROJECT_DIR`, else the checkout the hooks live in) and turns the edited path into a repo-relative one whether the harness sent `tool_input.file_path` (Claude Code, Gemini CLI), a top-level `file_path` (Cursor) or a `toolArgs` string with a `path` (Copilot). Paths outside the repo and unreadable payloads are skipped with a note on stderr, never blocked. `node .agents/hooks/test.js` pipes every fixture in `.agents/hooks/tests/` through its script (a hook, or `scripts/on-manifest-change.js --dry-run`) and compares exit code and output. A case that needs a file planted, or one kept absent, runs against a temporary root instead of the checkout, which a hook finds through `CLAUDE_PROJECT_DIR` and a script through `--root=<dir>`. The suite then runs the in-process checks in `self-checks.js` and the decision tables in `tables.js`, and holds the upstream to the same harness invariants a target runs. `check-edit.js` runs that suite itself whenever a hook, a script under `scripts/`, a table there or a Git hook changes. The suite stays upstream; a target runs `node scripts/check-harness.js`.
 
 ## Agents
 
@@ -123,7 +125,7 @@ What each tool reads, what is already in the repo, and what you must create for
 | Need | File | In repo |
 | --- | --- | --- |
 | Instructions | `CLAUDE.md` containing `@AGENTS.md` (Claude Code does not read `AGENTS.md` itself) | yes |
-| Skills | `.claude/skills/<name>` → symlink to `../../.agents/skills/<name>` | yes |
+| Skills | `.claude/skills` → symlink to `../.agents/skills` | yes |
 | Hooks | `.claude/settings.json` → `hooks.SessionStart`, `PreToolUse` (matcher `Bash`), `PostToolUse` (matcher `Edit\|Write\|MultiEdit`), each `{"type":"command","command":"node \"$CLAUDE_PROJECT_DIR/.agents/hooks/<hook>.js\""}` | yes |
 | Agents | `.claude/agents` → symlink to `../.agents/agents`; frontmatter `name`, `description` (+ optional `tools`, `model`, `skills`) | yes |
 | Per-developer overrides | `.claude/settings.local.json` (git-ignored) | no |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salaros/ai-harness",
-  "version": "0.2.3",
+  "version": "0.2.7",
   "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/README.md

@@ -18,12 +18,24 @@ 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.
+  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.
+- 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, …)`
+  inside), because `chdir` moves the working directory for the caller too.
+  `docs-check.js` does both: it chdirs nothing, and its command line resolves
+  the root itself.
 - Every script starts with a short comment describing what it does and how
   to call it; scripts that take arguments print usage when run with `-h`.
 - Node, so scripts run the same on Linux, macOS and Windows without a shell
-  adapter; `.githooks/post-merge` is the one exception, since Git always
-  runs it through its own bundled shell.
+  adapter. The files in `.githooks/` are the exception, since Git runs a hook
+  through its own bundled shell, so each is two lines that find the repo root
+  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.
 - Scripts must be idempotent where possible — running them twice should not
   break anything.
   

package/scripts/lib.js

@@ -4,7 +4,9 @@
 // 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.chdirRoot();            // cd to the repo root (this file is one level under it), return it
+//   const root = lib.root();                 // the repo root: --root=<dir> if given, else one level above this file
+//   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
 //   lib.node(["scripts/skills.js", "missing"]) // run a script with this node; { status, output }
 //   lib.shell("npm install")                 // run a command through the OS shell
@@ -13,13 +15,27 @@ const fs = require("fs");
 const path = require("path");
 const { spawnSync } = require("child_process");
 
-// Every script under scripts/ resolves the repo root from its own location (scripts/README.md,
-// "Conventions") and chdirs there so its relative paths (SKILL.md files, README.md, stacks.tsv)
-// work no matter where it was invoked from.
+// 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.
+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 args = () => process.argv.slice(2).filter(a => !a.startsWith(ROOT_FLAG));
+
 function chdirRoot() {
-    const root = path.resolve(__dirname, "..");
-    process.chdir(root);
-    return root;
+    const dir = root();
+    process.chdir(dir);
+    return dir;
 }
 
 function stdin() { try { return fs.readFileSync(0, "utf8"); } catch { return ""; } }
@@ -39,4 +55,4 @@ function readTsv(file) {
         .map(l => l.split("\t"));
 }
 
-module.exports = { chdirRoot, stdin, run, node, shell, readTsv };
+module.exports = { root, args, ROOT_FLAG, chdirRoot, stdin, run, node, shell, readTsv };

package/scripts/update-harness.js

@@ -188,11 +188,13 @@ function policies(templateDir) {
 // First match wins, so the table's order is its precedence. A row ending in / covers everything under it.
 // `optional:<flag>` is seeded only when the run asked for it, and is otherwise not installed at all:
 // the docs site is the case, useful to some projects and dead weight in the rest.
-function policyFor(rows, file) {
+// `wants` answers whether the run asked for an optional part, so the table's meaning does not depend
+// on the process's own argv and a test can ask what a repo would get either way.
+function policyFor(rows, file, wants) {
     const row = rows.find(r => r.path.endsWith("/") ? file.startsWith(r.path) : file === r.path);
     if (!row) return "merge";               // anything the upstream ships and nobody classified is harness
     if (!row.policy.startsWith("optional:")) return row.policy;
-    return flag(`--${row.policy.slice("optional:".length)}`) ? "seed" : "template";
+    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
@@ -349,6 +351,69 @@ const isCrlf = text => (text.match(CRLF) || []).length * 2 > (text.match(LF) ||
 const toLf = text => text.replace(CRLF, "\n");
 const asFound = (text, crlf) => crlf ? text.replace(LF, "\r\n") : text;
 
+// ---------------------------------------------------------------- the decision
+//
+// What happens to one file the target already has, decided apart from doing it. Everything these two
+// read is an argument, including the three things they cannot compute -- the base's text, the search
+// for a base when the receipt has none, and the three-way merge itself -- so the caller passes them
+// in and the loop below is left reading, writing and reporting.
+//
+// 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.
+
+// A file with no lines to merge: it is the upstream's copy or it is the project's, and the base
+// decides which. A logo the project replaced stays replaced.
+function decideBinary({ held, theirs, hasBase, adopt }, { baseBytes }) {
+    if (same(held, theirs)) return { outcome: "unchanged", bucket: null, text: null };
+    const was = hasBase ? baseBytes() : null;
+    if (adopt || same(held, was)) return { outcome: adopt ? "adopted" : "written", bucket: "written", text: theirs };
+    return { outcome: hasBase ? "yours, binary" : "yours, no base", bucket: "kept", text: null };
+}
+
+// A text file. `raw` is what is on disk, in whatever line endings it has; `theirs` is the upstream's,
+// always LF. The comparison and the merge happen in LF and the result is written back in the endings
+// the file already had, so a Windows checkout does not read as edited from top to bottom.
+function decideText({ policy, raw, theirs, hasBase, adopt }, { baseText, recoverBase, merge }) {
+    const crlf = isCrlf(raw);
+    const ours = toLf(raw);
+    const keep = { outcome: hasBase ? "yours, new here" : "yours, no base", bucket: "kept", text: null };
+
+    if (ours === theirs) return { outcome: "unchanged", bucket: null, text: null };
+    // Before the base logic, not inside it: a repo that needs adopting usually has a receipt
+    // already, written by the install that kept the stale files in the first place.
+    if (adopt) return { outcome: "adopted", bucket: "written", text: asFound(theirs, crlf) };
+    // Markers an earlier run wrote and nobody resolved. Left to the merge, the marked-up file is now
+    // its own nearest base, so the merge takes it whole, the run says "unchanged" and a half-merged
+    // harness passes as settled. Named instead, and the run exits 1 until someone resolves it or
+    // --adopt above throws it away.
+    if (MARKED.test(ours)) return { outcome: "STILL OPEN", bucket: "conflicted", text: null };
+
+    // A reconcile file is one the harness cannot work around: AGENTS.md is the map every agent reads
+    // and holds the table docs-check parses, and docs/README.md says what the chain puts where.
+    // Keeping a stale one leaves a repo that looks installed and behaves like the version it came
+    // from, so these are merged even when the receipt is missing. Nothing in the upstream's history
+    // matching means this copy was written by hand, and an empty base makes the whole file one
+    // conflict -- the honest answer: both versions are there to read, and the run exits 1.
+    let from = hasBase ? baseText() : null;
+    if (from === null && policy === "reconcile") from = recoverBase(ours);
+    if (from === null && policy === "reconcile") from = "";
+    if (from === null) return keep;
+
+    if (ours === from) return { outcome: "written", bucket: "written", text: asFound(theirs, crlf) };
+    const merged = merge(from, ours, theirs);
+    if (merged.failed) return { outcome: "yours, merge failed", bucket: "kept", text: null };
+    const result = asFound(merged.text, crlf);
+    if (merged.conflicts) return { outcome: "CONFLICT", bucket: "conflicted", text: result };
+    // A file that keeps a local edit merges cleanly on every later run and comes out the same every
+    // time. Reported as merged each run it reads as churn, and the reader goes looking for a change
+    // nobody made, so what the run did is decided by the result, not the route.
+    if (result === raw) return { outcome: "unchanged", bucket: null, text: null };
+    return { outcome: "merged", bucket: "merged", text: result };
+}
+
 function write(target, file, text, exec) {
     const full = path.join(target, file);
     if (dryRun) return;
@@ -361,42 +426,20 @@ function write(target, file, text, exec) {
 
 // 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. The suite
-// answers all of that, and it is the upstream's own: fixtures that prove a harness are no use to a
-// project carrying one, so they do not travel.
+// 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 are borrowed. Written in, run, and taken away again, leaving the repo as the install left
-// it. Running them from the upstream checkout instead would be tidier and does not work: both
-// lib.js files resolve the repo root from __dirname with no override, so the suite only ever tests
-// the checkout it sits in.
-const SUITE = [".agents/hooks/test.js", ".agents/hooks/tests/"];
-const wantedBySuite = file => SUITE.some(p => p.endsWith("/") ? file.startsWith(p) : file === p);
-
-function selfCheck(target, templateDir, head, files) {
-    const borrowed = [];
-    for (const { file } of files) {
-        if (!wantedBySuite(file)) continue;
-        // Anything already at one of these paths is the project's own: it is not overwritten here,
-        // and the cleanup below must not remove it either, so it is left out of the borrowed list.
-        if (fs.existsSync(path.join(target, file))) continue;
-        const text = blob(templateDir, head, file);
-        if (text === null) continue;
-        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 {
-        const r = lib.node([path.join(target, ".agents/hooks/test.js")], { cwd: target });
-        const lines = r.output.split(/\r?\n/).filter(l => l.trim());
-        return { failed: r.status !== 0, summary: lines[lines.length - 1] || "no output", output: r.output };
-    } finally {
-        // Only what this function wrote, and only the directories that writing it created.
-        for (const file of borrowed) { try { fs.rmSync(path.join(target, file)); } catch { /* already gone */ } }
-        const dirs = [...new Set(borrowed.map(f => path.dirname(f)))].sort((a, b) => b.length - a.length);
-        for (const dir of dirs) { try { fs.rmdirSync(path.join(target, dir)); } catch { /* the project's, or not empty */ } }
-    }
+// 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
@@ -440,13 +483,14 @@ function main() {
         }
 
         const rows = policies(templateDir);
+        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);
+            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
@@ -491,54 +535,20 @@ function main() {
             }
             // merge
             if (!exists) { write(target, file, theirs, exec); step(policy, m, "written", file, "written"); continue; }
-            // Binary: there are no lines to merge, so it is the upstream's copy or it is the
-            // project's, and the base decides which. A logo the project replaced stays replaced.
-            if (Buffer.isBuffer(theirs)) {
-                const held = fs.readFileSync(full);
-                if (same(held, theirs)) { step(policy, m, "unchanged", file); continue; }
-                const was = base === null ? null : blob(templateDir, base, file);
-                if (adopt || same(held, was)) {
-                    write(target, file, theirs, exec);
-                    step(policy, m, adopt ? "adopted" : "written", file, "written");
-                } else step(policy, m, base === null ? "yours, no base" : "yours, binary", file, "kept");
-                continue;
-            }
-            const raw = fs.readFileSync(full, "utf8");
-            const crlf = isCrlf(raw);
-            const ours = toLf(raw);
-            if (ours === theirs) { step(policy, m, "unchanged", file); continue; }
-            // Before the base logic, not inside it: a repo that needs adopting usually has a
-            // receipt already, written by the install that kept the stale files in the first place.
-            if (adopt) { write(target, file, asFound(theirs, crlf), exec); step(policy, m, "adopted", file, "written"); continue; }
-            // Markers an earlier run wrote and nobody resolved. Left to the merge, the marked-up file
-            // is now its own nearest base, so the merge takes it whole, the run says "unchanged" and
-            // a half-merged harness passes as settled. Named instead, and the run exits 1 until
-            // someone resolves it or --adopt above throws it away.
-            if (MARKED.test(ours)) { step(policy, m, "STILL OPEN", file, "conflicted"); continue; }
-            // A reconcile file is one the harness cannot work around: AGENTS.md is the map every
-            // agent reads and holds the table docs-check parses, and docs/README.md says what the
-            // chain puts where. Keeping a stale one leaves a repo that looks installed and behaves
-            // like the version it came from, so these are merged even when the receipt is missing.
-            let from = base === null ? null : blob(templateDir, base, file);
-            if (from === null && policy === "reconcile") from = recoverBase(templateDir, file, ours);
-            if (from === null && policy === "reconcile") {
-                // Nothing in the upstream's history matches, so this copy was written by hand. An
-                // empty base makes the whole file one conflict, which is the honest answer: both
-                // versions are there to read, and the run exits 1 rather than pretending.
-                from = "";
-            }
-            if (from === null) { step(policy, m, base === null ? "yours, no base" : "yours, new here", file, "kept"); continue; }
-            if (ours === from) { write(target, file, asFound(theirs, crlf), exec); step(policy, m, "written", file, "written"); continue; }
-            const merged = threeWay(from, ours, theirs);
-            if (merged.failed) { step(policy, m, "yours, merge failed", file, "kept"); continue; }
-            const result = asFound(merged.text, crlf);
-            if (merged.conflicts) { write(target, file, result, exec); step(policy, m, "CONFLICT", file, "conflicted"); continue; }
-            // A file that keeps a local edit merges cleanly on every later run and comes out the same
-            // every time. Reported as merged each run it reads as churn, and the reader goes looking
-            // for a change nobody made, so what the run did is decided by the result, not the route.
-            if (result === raw) { step(policy, m, "unchanged", file); continue; }
-            write(target, file, result, exec);
-            step(policy, m, "merged", file, "merged");
+
+            // 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);
         }
 
         phase("skeletons a project starts with");
@@ -552,8 +562,8 @@ function main() {
                 updated: new Date().toISOString().slice(0, 10),
             }, null, 2) + "\n");
             finish(target);
-            // After finish(), because the suite checks the links relink has just written.
-            if (!flag("--no-check")) notes.check = selfCheck(target, templateDir, head, files);
+            // 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 {
@@ -653,19 +663,23 @@ function report(target, head, ref, base) {
     }
     if (notes.conflicted.length) {
         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`);
+        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}, run from the upstream suite and removed again`);
+    else if (check) say(`\nself check: ${check.summary}`);
 
     if (!dryRun) {
-        const suite = fs.existsSync(path.join(target, ".agents/hooks/test.js"));
-        say(`\nIn ${target}, point Git at the hooks once per clone:`);
-        say(`  node scripts/githooks-init.js${suite ? " && node .agents/hooks/test.js" : " && node scripts/docs-check.js"}`);
+        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);
 }
 
-main();
+// 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 = { policyFor, decideText, decideBinary, lineCounts, overlap, NEAREST };
+
+if (require.main === module) main();