@salaros/ai-harness 0.2.6 → 0.2.8

package/LICENSE

@@ -1,14 +1,21 @@
+MIT License
+
 Copyright (c) 2019 CODECAVE
 
-All rights reserved.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-Redistribution and use in source and binary forms, with or without 
-modification, are strictly prohibited without prior written permission 
-from the copyright holder.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
-"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
-LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 
-A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
-HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
-SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,186 +1,102 @@
 # AI harness
 
-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`.
+A starting point for projects built with AI coding agents. It gives every agent the same instructions, skills, safety hooks and documentation workflow, whether you use Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI or OpenCode.
 
-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.
+It assumes no language or framework. What you put in `src/` decides the stack.
 
-## Adding the harness to a repository you already have
+## What you get
 
-Starting a project from scratch is a clone of this repository. Adding the harness to a repository that already exists, and keeping it current afterwards, is one command run from that repository's root:
+- **`AGENTS.md`**: one instruction file that every agent reads.
+- **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.
 
-```bash
-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.
+## Requirements
 
-`scripts/harness-files.tsv` is the table behind all of this, one row per path.
+- [Node.js](https://nodejs.org) 22 or newer
+- Git
+- On Windows: Developer Mode on, and `git config --global core.symlinks true` set **before** you clone
 
-Running it again updates. The first run writes `harness-lock.json` naming the upstream commit it took, which gives a later run a merge base: a harness file nobody edited takes the new version, an edited one keeps its edits and gains the changes around them, and only a real collision is written with conflict markers, reported, and exits non-zero. That is how `AGENTS.md` gains a new section while keeping your own rules, and how `docs/agents/issue-tracker.md` keeps your project key.
+## Installation
 
-Two files are merged even on a first install, where there is no receipt to take a base from: `AGENTS.md`, the map every agent reads and the table `docs-check` parses, and `docs/README.md`, which says what the chain puts where. Keeping a stale copy of either leaves a repo that looks installed and behaves like the version it came from, so the installer finds the base instead — the upstream version yours is closest to is where you forked from, whatever a receipt would have said. A copy nobody edited merges cleanly; an edited one keeps its edits and gains the rest. A file written from scratch matches nothing in the upstream's history and is written with conflict markers, so both versions are there to read.
-
-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.
-
-That first install writes a receipt even though it kept the old files, so `--adopt` has to keep working afterwards — it is normally the self check that tells you the harness is stale, and by then the receipt exists. A run at the recorded commit says so and takes every harness file again, rather than answering the one command that fixes it with "nothing to update".
-
-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.
-2. Clone, then install the Git hooks once: `node scripts/githooks-init.js`. Node is the only runtime the harness needs; on Windows nothing else (no `sh`) is required.
-3. Run the `project-init` skill (`/project-init` in Claude Code). It asks, through the tool's own question prompt, what the project is, where the requirements live, the stack and, if the project has one, the issue tracker, and writes the answers to `MEMORY.md`, this README and `docs/agents/issue-tracker.md`. It hands you the scaffold commands for the stack; running them is up to you.
-4. Skills are vendored in `.agents/skills`, so there is nothing to install. To add one: `npx skills add <owner/repo> -s <skill> -a claude-code codex -y`, then `node scripts/skills.js relink`, then commit.
-5. Open the repo in your AI tool and check the section for your tool under [Files per AI tool](#files-per-ai-tool). Authorise the Atlassian MCP server if the project tracks work in Jira, and the Figma one if it has designs; both are optional, and a project that plans in `docs/` and has no designs needs neither. See [MCP servers](#files-per-ai-tool).
-
-## Layout
-
-| Path | What it is |
-| --- | --- |
-| `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, 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 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. |
-| `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. |
-| `.skip-project-init` | Untracked, ignored, created by hand: it tells the initialisation gate that this clone has no project to configure, such as the upstream's own repo. Never committed, so it stays with whoever made it. |
-| `workflows/` | Workflow specs written by `loop-me`. |
-| `.scratch/` | Committed working files: feature specs, ticket drafts, prototypes not yet on a branch. |
-| `.mcp.json`, `opencode.json` | MCP server registrations for Claude Code and OpenCode: Atlassian for Jira, Figma for designs. Both are optional; a project with no tracker and no designs authorises neither. |
-
-## 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` link.
+### Start a new project
 
 ```bash
-npx skills add mattpocock/skills -s wait-what -a claude-code codex -y   # add a skill
-npx skills remove wait-what -y                                       # remove one
-npx skills update                                                  # newer versions of everything
-node scripts/skills.js relink                                      # after any of the above, and after writing a local skill
+git clone https://github.com/salaros/ai-harness.git my-project
+cd my-project
+node scripts/githooks-init.js
 ```
 
-- 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 the test suite 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`.
-
-`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.
-
-## Hooks
-
-Three Node scripts in `.agents/hooks/`, run with the `node` on your PATH (Windows has no `sh` on its PATH by default, and only Claude Code and Git bring their own). Each reads the harness's JSON payload from stdin, prints a message, and uses the exit code every harness understands the same way: `0` = fine, `2` = block or send the message back to the agent.
+Then open the folder in your AI tool and run the `project-init` skill (`/project-init` in Claude Code). It asks what the project is, where its requirements live, its stack and its issue tracker, and records the answers in `MEMORY.md`. The Git hooks refuse commits until it has run.
 
-| Script | Event | Does |
-| --- | --- | --- |
-| `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. |
+### Add the harness to an existing repository
 
-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.
+From the repository's root:
 
-`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.
+```bash
+npx @salaros/ai-harness
+```
 
-## Agents
+The installer adds the harness files and leaves your own work alone: it never writes `README.md` or `LICENSE`, and it adds a folder README only where one is missing. It records the upstream commit it installed in `harness-lock.json`.
 
-Agent definitions live in `.agents/agents/*.md`: YAML frontmatter with `name` and `description`, then the system prompt. The format is the one Claude Code, Cursor and Gemini CLI read directly; Codex and Copilot need a copy in their own shape (see their sections). Each agent routes a request to the skills it owns and runs them to their own definition of done. A row that two or three agents read lives in `.agents/routing.md` instead, in a section per audience that each agent names in its Route step; where an agent's own table and a section cover one trigger, the agent's row wins. A row every agent reads is not routing at all: it goes in `AGENTS.md` ("Working here"), which every session loads.
+Run the same command again to update. Files you haven't edited take the new version, files you have edited keep your changes and gain the new ones, and a real conflict is written with conflict markers and reported.
 
-| Agent | For |
+| Option | Effect |
 | --- | --- |
-| `engineer` | Engineering tasks bigger than a one-line edit, and the ADR → SPEC → TDD → IPLAN → Code half of the documentation chain |
-| `business-analyst` | Requirements, process design, interface contracts, agent-ready briefs, the BRD → PRD → EARS → BDD half of the documentation chain |
-| `devops` | Containers, CI/CD, Kubernetes, infrastructure as code, rollouts and incidents |
-| `assistant` | Non-technical colleagues |
-
-Which skills an agent routes to is the route table in its own file; `node scripts/skills.js list` prints the same mapping from the other direction, one row per skill.
+| `--dry-run` | Show what would change, write nothing |
+| `--quiet` | Print only the summary |
+| `--ref <tag>` | Install a fixed version instead of the latest `master` |
+| `--adopt` | Replace every harness file with the upstream's, for repos installed before `harness-lock.json` existed. Discards your edits to those files. |
+| `--astro-docs` | Also install `tools/docs-site/`, a website that renders your documentation |
+| `--no-check` | Skip the check the installer runs after writing |
+| `--help` | Print the options and exit. Any argument not listed here stops the installer before it writes. |
 
-## Files per AI tool
+The npm package holds only the installer. It fetches the harness from `master` at run time, so two runs a month apart may install different skills. Use `--ref` when you need the same result every time.
 
-What each tool reads, what is already in the repo, and what you must create for that tool. Paths are relative to the repo root. Only the Claude Code wiring has been run; the other rows come from each tool's own documentation.
+## Usage
 
-### Claude Code
+Talk to your agent as usual. `AGENTS.md` tells it which skill fits the task. You can also call a skill or an agent by name:
 
-| Need | File | In repo |
-| --- | --- | --- |
-| Instructions | `CLAUDE.md` containing `@AGENTS.md` (Claude Code does not read `AGENTS.md` itself) | 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 |
-
-Invoke an agent with "use the engineer agent to …", or a skill with `/tdd`, `/grilling`, and so on. On Windows the symlinks need Developer Mode and `core.symlinks=true` (see Getting started); if you cannot use symlinks, run `npx skills add … --copy` and copy `.agents/agents/*.md` into `.claude/agents/`.
-
-### Other tools
+```text
+/grilling            stress-test an idea before writing requirements
+/brd                 write a business requirements document
+/tdd                 build a feature test-first
+use the engineer agent to implement docs/spec/0001-billing.md
+```
 
-| Tool | Instructions | Skills | Hooks | Agents | MCP | Notes |
-| --- | --- | --- | --- | --- | --- | --- |
-| OpenAI Codex | `AGENTS.md`, read natively | `.agents/skills/`, read natively | create `.codex/hooks.json`, same shape as `.claude/settings.json` | create `.codex/agents/<name>.toml`, one per agent | create `.codex/config.toml` with `[mcp_servers.atlassian]`, then `codex mcp login atlassian` | Edits arrive as `apply_patch` commands with the paths inside the patch; `check-edit.js` skips them until `lib.js` learns that shape. [Docs](https://developers.openai.com/codex/hooks) |
-| Cursor | `AGENTS.md`, read natively | `.agents/skills/`, read natively | create `.cursor/hooks.json` (`sessionStart`, `beforeShellExecution`, `afterFileEdit`) | create `.cursor/agents/<name>.md`: copy or symlink | create `.cursor/mcp.json` (`mcpServers`, no `type`) | Exit 2 blocks; `file_path` and `command` are top-level payload fields, which `lib.js` reads. [Docs](https://cursor.com/docs/agent/hooks) |
-| GitHub Copilot | `AGENTS.md`, read natively | `.agents/skills/`, read natively | create `.github/hooks/*.json` (`sessionStart`, `preToolUse`, `postToolUse`) | create `.github/agents/<name>.agent.md`: copy with the suffix | create `.vscode/mcp.json` (`servers`) | `toolArgs` is a JSON string inside the payload, which `lib.js` parses; any non-zero exit denies. [Docs](https://docs.github.com/en/copilot/reference/hooks-reference) |
-| Gemini CLI | `GEMINI.md` by default; point it at `AGENTS.md` through `.gemini/settings.json` | `.agents/skills/`, read natively | create `.gemini/settings.json` with `hooks` (`SessionStart`, `BeforeTool`, `AfterTool`) | create `.gemini/agents/<name>.md`: copy or symlink | create `.gemini/settings.json` with `mcpServers` (`httpUrl`) | Same payload shape as Claude Code; timeouts in milliseconds and a `name` per hook. [Docs](https://geminicli.com/docs/hooks/) |
-| OpenCode | `AGENTS.md`, read natively | `.agents/skills/`, read natively | a JS plugin under `.opencode/plugins/` that shells out to the three scripts; there are no command hooks | none | `opencode.json`, in repo | [Docs](https://opencode.ai/docs/plugins/) |
-| Anything else | `AGENTS.md` | read each `SKILL.md` description and load what matches, as `AGENTS.md` says | wire the three scripts to the tool's events: payload on stdin, exit 2 blocks | an agent file pasted as the system prompt | its own file | |
+Everyday commands:
 
-Two servers are registered, and neither is required: Atlassian, whose URL and Jira conventions the skills follow are in `docs/agents/issue-tracker.md`, and Figma at `https://mcp.figma.com/mcp`, used by the `figma` skills. Authorise the one you use. A project that plans its work in `docs/` needs no tracker, and one with no designs yet needs no Figma. Each is authorised in the tool's own way, and the `figma` skill's `references/figma-mcp-config.md` covers a bearer token for a harness that cannot do the interactive flow. The question tool per harness is in `docs/agents/questions.md`.
+```bash
+node scripts/docs-check.js                         # check the documentation chain
+node scripts/check-harness.js                      # check the harness itself
+npx skills add <owner/repo> -s <skill> -a claude-code codex -y
+node scripts/skills.js relink                      # run after adding or updating skills
+```
 
-## Documentation chain
+Claude Code works as soon as you clone. Other tools need a small config file for hooks and agents; [.agents/README.md](.agents/README.md#files-per-ai-tool) lists the files for each tool.
 
-The chain BRD → PRD → EARS → BDD → ADR → SPEC → TDD → IPLAN → Code, its folders and the skill for each stage are the table in `AGENTS.md` ("Documentation"); `docs/README.md` says what each document must contain. Documents are `docs/<stage>/NNNN-<slug>.md` and cite what they derive from; `scripts/docs-check.js` reads the stages from that table and verifies the IDs and citations, the edit hook runs it after every change under `docs/` or to `AGENTS.md`, and the `docs-check` skill repairs its findings.
+## Documentation
 
-## What each skill expects from the repo
+- [AGENTS.md](AGENTS.md): the rules every agent follows, including the documentation chain.
+- [docs/README.md](docs/README.md): what each document in the chain must contain.
+- [.agents/README.md](.agents/README.md): reference for the layout, skills, hooks, agents, per-tool setup and what each skill expects.
+- `src/`, `tests/`, `scripts/`, `tools/` and `docs/` each have a README saying what belongs in them.
 
-Most skills need nothing beyond `AGENTS.md` and their own folder. The files under `docs/agents/` are configuration the harness ships; everything else in the table below is created by the skill itself when first needed.
+## Releasing
 
-### Shared setup: `docs/agents/`
+Maintainers publish the installer to npm by pushing an annotated version tag on `master`:
 
-A tracker is optional, and it does not have to be Jira: a project can plan entirely in `docs/`, recording `Issue tracker: none`. `code-review`, `to-tickets` and `triage` are the skills that read the issue-tracker configuration, and each asks for one when it is reached for without it. When there is a tracker the harness ships configured for **Jira through the Atlassian MCP server**:
+```bash
+git tag -a 0.2.8 -m "0.2.8" && git push origin 0.2.8
+```
 
-- `docs/agents/issue-tracker.md`: which MCP tools create, read, label, link and close issues. **Replace `TODO-PROJECT-KEY` with your Jira project key** before first use.
-- `docs/agents/triage-labels.md`: maps the five triage roles (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`) to plain Jira labels of the same names.
-- `docs/agents/domain.md`: tells skills to read `CONTEXT.md` and `docs/adr/` before exploring, and to stay silent when they are absent.
-- `docs/agents/questions.md`: the question tool each harness offers (Claude Code, OpenCode, Copilot and so on) and the plain-text fallback, so interviews and confirmations always go through the tool. `AGENTS.md` ("Working here") makes this a rule for every skill.
-- The `## Agent skills` section in `AGENTS.md` points at the three files.
+The [release workflow](.github/workflows/release.yml) runs the tests, writes the tag's version into `package.json` and publishes. Leave the version in `package.json` at `0.0.0`.
 
-To switch trackers (GitHub via `gh`, GitLab via `glab`, or local Markdown under `.scratch/`), run `/setup-matt-pocock-skills` in your agent; the skill is vendored and rewrites the three files and the `AGENTS.md` block from its templates.
+## License
 
-### Per skill
+MIT; see [LICENSE](LICENSE). Vendored skills keep their own licences, listed in [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).
 
-| Skill | Reads | Writes |
-| --- | --- | --- |
-| `code-review` | `docs/agents/issue-tracker.md`; `CODING_STANDARDS.md`; the spec, from an issue in the commit messages, a path you pass, or a file under `docs/`, `specs/` or `.scratch/` matching the branch | nothing |
-| `to-tickets` | `docs/agents/issue-tracker.md` | drafts under `.scratch/<feature-slug>/`, then Jira issues in dependency order |
-| `triage` | `docs/agents/issue-tracker.md`, `docs/agents/triage-labels.md`, `.out-of-scope/` | `.out-of-scope/<concept>.md` per rejected request; Jira labels and comments |
-| `domain-modeling`, also through `grill-with-docs`, `improve-codebase-architecture` and `triage` | `CONTEXT.md`, `docs/adr/` | `CONTEXT.md`, `docs/adr/NNNN-<slug>.md`; `CONTEXT-MAP.md` only in a multi-context repo |
-| `brd`, `prd`, `feature-forge`, `bdd-scenarios`, `design-doc`, `create-implementation-plan` | the document one stage upstream; `CONTEXT.md` when present | `docs/<stage>/NNNN-<slug>.md` per the `AGENTS.md` table (`.scratch/<feature>/` for the plan), whatever path the skill's own instructions name |
-| `docs-check` | the `AGENTS.md` table, `docs/` | repairs in place |
-| `loose-ends` | `TODO.md` | `TODO.md` at the repo root, created on the first entry |
-| `project-init` | answers from the harness's question tool | `MEMORY.md`, the Project section of this README, and the key and site in `docs/agents/issue-tracker.md` when the project has a tracker |
-| `teach` | the working directory as a workspace | `MISSION.md`, `RESOURCES.md`, `NOTES.md`, `reference/`, `lessons/`, `learning-records/`, `assets/` |
-| `loop-me` | `NOTES.md`, shared with `teach` | `workflows/<name>.md`, `NOTES.md` |
-| `implement`, `tdd`, `prototype` | a spec or tickets; the stack's test runner, type checker and task runner | code under `src/` and `tests/`; prototypes on a throwaway branch |
-| `retro` | the session logs of the agent that ran | proposed edits to `AGENTS.md`, `CODING_STANDARDS.md`, the docs and the skills |
-| `agent-browser` | the `agent-browser` CLI (`npx agent-browser` fetches it) | nothing in the repo |
+## Contact
 
-`handoff` and `improve-codebase-architecture` write to the OS temp directory. `setup-matt-pocock-skills` rewrites `docs/agents/` and the `Agent skills` block of `AGENTS.md` when the tracker changes. Every other skill reads nothing but `AGENTS.md`.
+Maintained by CODECAVE. Report problems and suggestions in [GitHub issues](https://github.com/salaros/ai-harness/issues).

package/package.json

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

@@ -24,6 +24,7 @@
 //   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             take every harness file from the upstream, losing local edits
+//   node scripts/update-harness.js --help              print this usage and exit
 // 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
@@ -41,6 +42,50 @@ const DEFAULT_REF = "master";
 const argv = process.argv.slice(2);
 const flag = name => argv.includes(name);
 const value = (name, fallback) => { const i = argv.indexOf(name); return i >= 0 && argv[i + 1] ? argv[i + 1] : fallback; };
+// Every argument the installer knows. An optional part of the harness adds its own flag through the
+// manifest (optional:<flag>), so those are checked once the upstream checkout is read. Anything else
+// stops the run before a file is written: this script installs when it is run, so a mistyped
+// --dry-rn, or a --help it did not understand, used to install for real.
+const FLAGS = ["--dry-run", "--adopt", "--quiet", "--no-check", "--help", "-h"];
+const VALUES = ["--ref", "--target", "--from"];
+function unknownArgs(args, optional) {
+    const known = [...FLAGS, ...optional.map(name => `--${name}`)];
+    const unknown = [];
+    for (let i = 0; i < args.length; i++) {
+        if (VALUES.includes(args[i])) i++;
+        else if (!known.includes(args[i])) unknown.push(args[i]);
+    }
+    return unknown;
+}
+// The part of that check that needs no manifest, so a typo fails before the clone rather than after
+// it: anything not shaped like a flag, and anything a letter or two from a flag this script already
+// knows, which no optional part would be named.
+function mistypedArgs(args) {
+    const named = [...FLAGS, ...VALUES];
+    const near = (a, b) => {
+        const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+        for (let j = 1; j <= b.length; j++) d[0][j] = j;
+        for (let i = 1; i <= a.length; i++)
+            for (let j = 1; j <= b.length; j++)
+                d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        return d[a.length][b.length] <= 2;
+    };
+    const mistyped = [];
+    for (let i = 0; i < args.length; i++) {
+        if (VALUES.includes(args[i])) { i++; continue; }
+        if (named.includes(args[i])) continue;
+        if (!/^--[a-z0-9]+(-[a-z0-9]+)*$/.test(args[i]) || named.some(n => near(args[i], n))) mistyped.push(args[i]);
+    }
+    return mistyped;
+}
+// Read from the comment block at the top of this file, so the usage has one copy.
+function usage() {
+    const lines = fs.readFileSync(__filename, "utf8").split(/\r?\n/);
+    const start = lines.findIndex(l => l.startsWith("// Usage:"));
+    const out = [];
+    for (let i = start + 1; i < lines.length && lines[i].startsWith("//   "); i++) out.push(lines[i].slice(3).replace("node scripts/update-harness.js", "npx @salaros/ai-harness"));
+    return ["Installs or updates the agent harness in the current git repository.", "", "Usage:", ...out].join("\n");
+}
 const dryRun = flag("--dry-run");
 const adopt = flag("--adopt");
 
@@ -188,11 +233,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
@@ -291,10 +338,19 @@ const SKELETONS = {
     ],
 };
 
+// A repo that already has an INTENT.md names the product and its purpose there, so the MEMORY.md
+// laid down beside it leaves those two out rather than asking for them a second time.
+function skeletonLines(target, file, lines) {
+    if (file !== "MEMORY.md" || !fs.existsSync(path.join(target, "INTENT.md"))) return lines;
+    const facts = lines.filter(l => !/^- \*\*(?:Name|Purpose):\*\*/.test(l));
+    const first = facts.findIndex(l => l.startsWith("- **"));
+    return [...facts.slice(0, first), "The name and purpose are in `INTENT.md`, under `## Product`.", "", ...facts.slice(first)];
+}
+
 function skeletons(target) {
     for (const [file, lines] of Object.entries(SKELETONS)) {
         if (fs.existsSync(path.join(target, file))) { step("seed", "100644", "yours", file); continue; }
-        write(target, file, lines.join("\n"));
+        write(target, file, skeletonLines(target, file, lines).join("\n"));
         step("seed", "100644", "created", file, "seeded");
     }
 }
@@ -349,6 +405,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,47 +480,28 @@ 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
 
 function main() {
+    if (flag("--help") || flag("-h")) { console.log(usage()); return; }
+    const mistyped = mistypedArgs(argv);
+    if (mistyped.length) fail(`unknown argument(s): ${mistyped.join(" ")}. Nothing was written; run with --help for the options.`);
     const target = targetRoot();
     if (!fs.existsSync(path.join(target, ".git"))) fail(`${target} is not a git checkout`);
 
@@ -411,6 +511,14 @@ function main() {
     const { dir: templateDir, temporary } = templateCheckout(ref);
 
     try {
+        // Checked before anything is said about the target, so a bad argument is the only message.
+        const rows = policies(templateDir);
+        const optional = rows.filter(r => r.policy.startsWith("optional:")).map(r => r.policy.slice("optional:".length));
+        const unknown = unknownArgs(argv, optional);
+        if (unknown.length) {
+            if (temporary) fs.rmSync(templateDir, { recursive: true, force: true });
+            fail(`unknown argument(s): ${unknown.join(" ")}. Nothing was written; run with --help for the options.`);
+        }
         const head = at(templateDir, ["rev-parse", "HEAD"]).output.trim();
         // A base is what makes this an update rather than an overwrite. Without one -- a first
         // install, or an upstream whose history was rewritten -- an existing file is left alone
@@ -439,14 +547,14 @@ function main() {
             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 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 +599,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 +626,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 +727,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 = { unknownArgs, mistypedArgs, usage, policyFor, decideText, decideBinary, lineCounts, overlap, NEAREST, skeletonLines };
+
+if (require.main === module) main();