@salaros/ai-harness 0.1.0

package/LICENSE

@@ -0,0 +1,14 @@
+Copyright (c) 2019 CODECAVE
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without 
+modification, are strictly prohibited without prior written permission 
+from the copyright holder.
+
+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.

package/README.md

@@ -0,0 +1,176 @@
+# 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`.
+
+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.
+
+## Adding the harness to a repository you already have
+
+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:
+
+```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.
+
+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.
+
+`scripts/harness-files.tsv` is the table behind all of this, one row per path.
+
+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.
+
+Skills are added and updated, never removed: one you vendored yourself survives every update, and `skills-lock.json` is merged as a union.
+
+## 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, requirements location, stack, the frontend framework when the project has browser code, and the issue tracker when there is one), one per line. Written by the `project-init` skill; absent until it runs. |
+| `TODO.md` | The loose-ends ledger: questions nobody has answered, assumptions taken on trust, and work knowingly left undone. Follows the [todo-md standard](https://github.com/todo-md/todo-md) -- a `# TODO` header, one entry per line as `- [ ] <text> #<tag> (<source>)`, `@user` and indented subtasks optional -- so its tooling reads this file. Written by the `loose-ends` skill and absent until the first entry, since an empty ledger says less than no ledger. It departs from the standard in one place: a settled entry is deleted in the commit that settles it rather than kept as `[x]` or `[-]`, because entries nobody will act on are context every agent re-reads. Needs no issue tracker. |
+| `THIRD-PARTY-NOTICES.md`, `scripts/skill-licences.tsv` | Vendoring a skill copies someone else’s work here, and MIT and Apache-2.0 both ask that the copyright and permission notice travel with the copy; `npx skills` carries only what sits inside the skill folder, so an upstream keeping its licence at the repo root sends none. The TSV holds one row per upstream (SPDX id, copyright line, licence URL, and any restriction); `node scripts/skills.js notices` regenerates the notice from it and `skills-lock.json`. A new upstream with no row fails the harness suite. |
+| `skills-lock.json` | Written by `npx skills`: source, path and hash of every installed skill. The single record of what is installed; `node scripts/skills.js install` restores from it. |
+| `.agents/skills/<name>/` | The canonical, vendored copy of each skill (`SKILL.md` plus its reference files). |
+| `.agents/hooks/` | Harness-neutral hook scripts (see [Hooks](#hooks)). |
+| `.agents/agents/` | Agent definitions (see [Agents](#agents)). |
+| `scripts/update-harness.js`, `scripts/harness-files.tsv`, `harness-lock.json` | The installer, the table of what travels and what does not, and the receipt naming the upstream commit a repo last took. The first two are the upstream’s own and are never installed; the receipt is written into the repo being updated. |
+| `.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` links.
+
+```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
+```
+
+- 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.
+- `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.
+
+| 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. |
+
+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.
+
+## Agents
+
+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.
+
+| Agent | For |
+| --- | --- |
+| `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.
+
+## Files per AI tool
+
+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.
+
+### Claude Code
+
+| 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 |
+| 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
+
+| 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 | |
+
+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`.
+
+## Documentation chain
+
+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.
+
+## What each skill expects from the repo
+
+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.
+
+### Shared setup: `docs/agents/`
+
+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**:
+
+- `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.
+
+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.
+
+### Per skill
+
+| 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 |
+
+`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`.

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@salaros/ai-harness",
+  "version": "0.1.0",
+  "description": "Installs and updates the agent harness from its upstream repository: hooks, skills, agents and the documentation chain, merged into an existing repository without touching its own work.",
+  "bin": {
+    "ai-harness": "scripts/update-harness.js"
+  },
+  "files": [
+    "scripts/update-harness.js",
+    "scripts/lib.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/salaros/ai-harness.git"
+  },
+  "license": "MIT",
+  "keywords": [
+    "agent",
+    "skills",
+    "claude-code",
+    "git-hooks",
+    "harness",
+    "template"
+  ]
+}

package/scripts/README.md

@@ -0,0 +1,29 @@
+## Scripts
+
+Automation scripts for working with this repository. They are run by
+developers and CI, not by the application itself, and are never shipped as
+part of the product.
+
+### What belongs here
+
+- **Setup** — bootstrap a fresh clone (install dependencies, git hooks,
+  local configuration).
+- **Build and release** — compile, package, version, publish.
+- **Maintenance** — clean caches, regenerate code or docs, migrate data.
+- **CI helpers** — steps invoked from pipeline definitions, kept here so
+  they can also be run locally.
+
+### Conventions
+
+- 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.
+- 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.
+- Scripts must be idempotent where possible — running them twice should not
+  break anything.
+  

package/scripts/lib.js

@@ -0,0 +1,42 @@
+// scripts/lib.js
+// Small process and table-reading helpers shared by scripts and, through .agents/hooks/lib.js, by
+// the hooks. Nothing here knows about a harness's hook payload; that lives in .agents/hooks/lib.js,
+// 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
+//   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
+//   lib.readTsv("scripts/stacks.tsv")        // rows as arrays of cells; blank and # lines skipped
+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.
+function chdirRoot() {
+    const root = path.resolve(__dirname, "..");
+    process.chdir(root);
+    return root;
+}
+
+function stdin() { try { return fs.readFileSync(0, "utf8"); } catch { return ""; } }
+
+// Runs a command; output is stdout and stderr combined, status is the exit code (-1 if it could not start).
+function run(cmd, args, opts = {}) {
+    const r = spawnSync(cmd, args, { encoding: "utf8", ...opts });
+    const output = ((r.stdout || "") + (r.stderr || "")).replace(/\s+$/, "");
+    return { status: r.status === null ? -1 : r.status, output: r.error ? `${r.error.message}${output ? "\n" + output : ""}` : output };
+}
+const node = (args, opts) => run(process.execPath, args, opts);
+const shell = (cmd, opts) => run(cmd, [], { shell: true, ...opts });
+
+function readTsv(file) {
+    return fs.readFileSync(file, "utf8").split(/\r?\n/)
+        .filter(l => l.trim() && !l.startsWith("#"))
+        .map(l => l.split("\t"));
+}
+
+module.exports = { chdirRoot, stdin, run, node, shell, readTsv };

package/scripts/update-harness.js

@@ -0,0 +1,441 @@
+#!/usr/bin/env node
+// scripts/update-harness.js
+// Installs this repository's harness into another one, and updates it there afterwards. The
+// upstream keeps moving; a repo made from it fills the same tree with work of its own. This script
+// is the line between the two, and scripts/harness-files.tsv is where that line is written down.
+//
+// Updating is a three-way merge, not a copy. harness-lock.json at the target root records the
+// upstream commit the harness was last taken from, so an update has a base: the recorded commit's
+// version of a file, the target's version, and the new one. A file nobody edited takes the new
+// version outright. An edited one keeps its edits and gains the changes around them. Only a real
+// collision is written with conflict markers, and every one of those is reported and exits 1, so a
+// half-merged harness is never mistaken for a clean update.
+//
+// First run into a repo with no harness-lock.json is an install: there is no base, so every managed
+// file is written, and nothing that already exists is touched.
+//
+// Usage:
+//   node scripts/update-harness.js                     update this repo from the upstream it records
+//   node scripts/update-harness.js --dry-run           say what would change, write nothing
+//   node scripts/update-harness.js --ref v2            update from a tag or branch instead
+//   node scripts/update-harness.js --target ../other   install into or update another checkout
+//   node scripts/update-harness.js --from ../ai-harness use a checkout you already have, no clone
+//   node scripts/update-harness.js --astro-docs        add tools/docs-site, the Astro renderer for the chain
+//   node scripts/update-harness.js --no-check          install without proving it afterwards
+// 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
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const lib = require("./lib");
+
+const TEMPLATE = "https://github.com/salaros/ai-harness.git";
+const LOCK = "harness-lock.json";
+const MANIFEST = "scripts/harness-files.tsv";
+const DEFAULT_REF = "master";
+
+const argv = process.argv.slice(2);
+const flag = name => argv.includes(name);
+const value = (name, fallback) => { const i = argv.indexOf(name); return i >= 0 && argv[i + 1] ? argv[i + 1] : fallback; };
+const dryRun = flag("--dry-run");
+
+// ---------------------------------------------------------------- the target
+
+// Where the harness is going. Run from inside a project, that is the project: this script sits in
+// its scripts/ folder. Run through npx, the package is an extracted tarball with no .git of its own,
+// so the answer is the directory the user is standing in. One rule covers both, and --target covers
+// installing into a checkout from somewhere else entirely.
+function targetRoot() {
+    const given = value("--target", null);
+    if (given) return path.resolve(given);
+    const beside = path.resolve(__dirname, "..");
+    return fs.existsSync(path.join(beside, ".git")) ? beside : process.cwd();
+}
+
+// ---------------------------------------------------------------- the upstream
+
+// A clone deep enough to read the recorded commit: an update needs that commit's version of a file
+// as the merge base, and --depth 1 would not have it. Removed again unless the caller supplied one.
+function templateCheckout(ref) {
+    // The manifest is what makes a checkout usable here, so both routes are held to it: a --from
+    // that points somewhere else, and a --ref naming a branch or tag from before the table existed,
+    // fail the same way. Without this the run reaches readTsv and dies in a stack trace naming a
+    // temporary directory the reader has never heard of.
+    const usable = dir => fs.existsSync(path.join(dir, MANIFEST));
+    const given = value("--from", null);
+    if (given) {
+        const dir = path.resolve(given);
+        if (!usable(dir)) fail(`${dir} does not look like the upstream harness: no ${MANIFEST}`);
+        return { dir, temporary: false };
+    }
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "harness-"));
+    say(`cloning ${TEMPLATE} at ${ref}`);
+    const r = lib.run("git", ["clone", "--quiet", "--branch", ref, TEMPLATE, dir]);
+    if (r.status !== 0) fail(`could not clone the upstream at ${ref}\n${r.output}`);
+    if (!usable(dir)) {
+        fs.rmSync(dir, { recursive: true, force: true });
+        fail(`${TEMPLATE} at ${ref} carries no ${MANIFEST}, so there is nothing to install from; try another --ref`);
+    }
+    return { dir, temporary: true };
+}
+
+const at = (dir, args) => lib.run("git", ["-C", dir, ...args]);
+
+// The upstream's version of a path at a commit, or null when the file did not exist there. Also how
+// a missing base is detected: a rewritten history no longer holds the recorded commit.
+function blob(dir, commit, file) {
+    const r = at(dir, ["show", `${commit}:${file}`]);
+    return r.status === 0 ? r.output : null;
+}
+
+// ---------------------------------------------------------------- the manifest
+
+function policies(templateDir) {
+    return lib.readTsv(path.join(templateDir, MANIFEST)).map(([p, policy]) => ({ path: p, policy }));
+}
+
+// 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) {
+    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";
+}
+
+// Every path the upstream tracks, with the mode Git recorded. Mode 120000 is a symlink, and the
+// harness has two kinds: .claude/agents pointing at .agents/agents, and one per skill under
+// .claude/skills. Written as ordinary files they become text files holding a path, which is how a
+// harness ends up looking installed while the agent sees no skills and no agents at all.
+function templateFiles(dir) {
+    const r = at(dir, ["ls-files", "-s"]);
+    if (r.status !== 0) fail(`could not list the upstream's files\n${r.output}`);
+    return r.output.split(/\r?\n/).filter(Boolean).map(line => {
+        const [meta, file] = line.split("\t");
+        return { file, link: meta.startsWith("120000"), exec: meta.startsWith("100755") };
+    });
+}
+
+// Git runs a hook only if it is executable, and says nothing when it is not: an installed harness
+// whose hooks are mode 644 looks installed and gates nothing. The upstream records them 100755, so
+// that mode has to travel, and only Git can carry it. `chmod` alone is not enough -- on Windows
+// core.fileMode is false and the call does nothing, so the file would be staged 100644 later and the
+// hooks would run for whoever installed them and silently never run for anyone else. `git add
+// --chmod=+x` writes the mode into the index whether or not the file was tracked, which is why the
+// install stages these few files rather than leaving them for the project's own `git add`.
+function carryMode(target, file) {
+    try { fs.chmodSync(path.join(target, file), 0o755); } catch { /* the filesystem does not do modes */ }
+    const r = lib.run("git", ["-C", target, "add", "--chmod=+x", "--", file]);
+    if (r.status !== 0) say(`could not mark ${file} executable: ${r.output}`);
+}
+
+// A symlink recorded in Git is a blob holding its target. Windows needs Developer Mode and
+// core.symlinks=true for this to work at all, so a refusal is reported rather than thrown: the
+// harness still functions with the links missing, it is just invisible to the harnesses that read
+// them, and README says how to turn them on.
+function link(target, file, to) {
+    const full = path.join(target, file);
+    if (dryRun) return "written";
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    let existing = null;
+    try { existing = fs.lstatSync(full); } catch { /* absent */ }
+    if (existing) {
+        if (!existing.isSymbolicLink()) return "kept";       // something of the project's is in the way
+        if (fs.readlinkSync(full).split(path.sep).join("/") === to) return null;
+        fs.unlinkSync(full);
+    }
+    try {
+        fs.symlinkSync(to.split("/").join(path.sep), full, "dir");
+        return existing ? "merged" : "written";
+    } catch (e) {
+        say(`could not create the symlink ${file} -> ${to}: ${e.code || e.message}`);
+        return "kept";
+    }
+}
+
+// ---------------------------------------------------------------- skeletons
+
+// Three files the upstream does not ship, because there they would be lies: MEMORY.md
+// describes a project this repo is not, and CONTEXT.md and TODO.md are written by the skills that
+// own them, when there is something real to put in them. A repo that just took the harness has
+// neither the files nor any sign the harness expects them, so an empty one is laid down: it names
+// the file, says which skill fills it, and is valid to every check that reads it. Written only when
+// absent, and never touched again.
+const SKELETONS = {
+    "MEMORY.md": [
+        "# Project memory",
+        "",
+        "The facts no other file derives. Read this first. The `project-init` skill writes it, and the",
+        "`pre-commit` and `pre-push` hooks refuse to let work leave a clone while any value is still a",
+        "`<placeholder>`.",
+        "",
+        "- **Name:** <name>",
+        "- **Purpose:** <purpose>",
+        "- **Requirements:** <requirements>",
+        "- **Unit type:** <unit type>",
+        "- **Language:** <language>",
+        "- **Runtime / package manager:** <runtime>",
+        "",
+    ],
+    "CONTEXT.md": [
+        "# Context",
+        "",
+        "The project's glossary: one entry per term the code and the documents both use, in the words",
+        "the business uses. The `domain-modeling` skill writes an entry the moment a term is settled,",
+        "and the decisions those terms come out of live in `docs/adr/`.",
+        "",
+    ],
+    "TODO.md": [
+        "# TODO",
+        "",
+        "Loose ends, in the [todo-md](https://github.com/todo-md/todo-md) format the `loose-ends` skill",
+        "writes: `- [ ] <text> #question|#assumption|#deferred (<source>)`. An entry is deleted in the",
+        "commit that settles it rather than ticked, so the length of this file means something.",
+        "",
+    ],
+};
+
+function skeletons(target) {
+    for (const [file, lines] of Object.entries(SKELETONS)) {
+        if (fs.existsSync(path.join(target, file))) continue;
+        write(target, file, lines.join("\n"));
+        notes.seeded.push(file);
+    }
+}
+
+// ---------------------------------------------------------------- merging
+
+// git merge-file writes the merged result and reports the number of conflicts, or a negative status
+// for trouble. Used rather than a hand-rolled diff3 because the target already needs Git.
+function threeWay(base, ours, theirs) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "merge-"));
+    const f = n => path.join(dir, n);
+    try {
+        fs.writeFileSync(f("base"), base);
+        fs.writeFileSync(f("ours"), ours);
+        fs.writeFileSync(f("theirs"), theirs);
+        const r = lib.run("git", ["merge-file", "-L", "yours", "-L", "upstream (base)", "-L", "upstream (new)",
+            f("ours"), f("base"), f("theirs")]);
+        return { text: fs.readFileSync(f("ours"), "utf8"), conflicts: r.status > 0, failed: r.status < 0 };
+    } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+}
+
+// ---------------------------------------------------------------- reporting
+
+const notes = { written: [], merged: [], conflicted: [], seeded: [], kept: [], skipped: [], template: [], check: null };
+const say = m => console.log(m);
+function fail(m) { console.error(`update-harness: ${m}`); process.exit(1); }
+
+function write(target, file, text, exec) {
+    const full = path.join(target, file);
+    if (dryRun) return;
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, text);
+    if (exec) carryMode(target, file);
+}
+
+// ---------------------------------------------------------------- the self check
+
+// Merging is not checking. The installer knows it wrote a file; it cannot know whether the result
+// still works -- an AGENTS.md whose chain table no longer parses, routing sections naming an agent
+// this repo does not have, a skill nothing links to, an upstream with no licence row. 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.
+//
+// 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);
+    }
+    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 */ } }
+    }
+}
+
+// ---------------------------------------------------------------- the run
+
+function main() {
+    const target = targetRoot();
+    if (!fs.existsSync(path.join(target, ".git"))) fail(`${target} is not a git checkout`);
+
+    const lockPath = path.join(target, LOCK);
+    const previous = fs.existsSync(lockPath) ? JSON.parse(fs.readFileSync(lockPath, "utf8")) : null;
+    const ref = value("--ref", previous ? previous.ref : DEFAULT_REF);
+    const { dir: templateDir, temporary } = templateCheckout(ref);
+
+    try {
+        const head = at(templateDir, ["rev-parse", "HEAD"]).output.trim();
+        // A base is what makes this an update rather than an overwrite. Without one -- a first
+        // install, or an upstream whose history was rewritten -- an existing file is left alone
+        // instead of being guessed at, and the run says so.
+        let base = previous ? previous.commit : null;
+        if (base && at(templateDir, ["cat-file", "-e", `${base}^{commit}`]).status !== 0) {
+            say(`the recorded upstream commit ${base.slice(0, 8)} is not in ${TEMPLATE} any more, so this run has no merge base: existing files are left alone`);
+            base = null;
+        }
+        if (previous && base === head) { say(`harness is already at ${head.slice(0, 8)} (${ref}); nothing to update`); return; }
+
+        const rows = policies(templateDir);
+        const files = templateFiles(templateDir);
+        const skills = [];
+
+        for (const { file, link: isLink, exec } of files) {
+            const policy = policyFor(rows, file);
+            const theirs = blob(templateDir, head, file);
+            if (theirs === null) continue;
+            const full = path.join(target, file);
+            const exists = fs.existsSync(full);
+
+            if (policy === "template") { notes.template.push(file); continue; }
+            if (isLink) {
+                // A skill link is relink's to make, once the directory it lives in exists: it knows
+                // which skills this project actually has, where the upstream only knows its own.
+                if (policy === "skills") {
+                    if (!dryRun) fs.mkdirSync(path.dirname(full), { recursive: true });
+                    continue;
+                }
+                const how = link(target, file, theirs.trim());
+                if (how) notes[how].push(file);
+                continue;
+            }
+            if (policy === "skills") { skills.push(file); continue; }
+            // Reported only when the target actually has it: "left alone, yours" about a file the
+            // repo does not have names something that was never there.
+            if (policy === "skip") { if (exists) notes.skipped.push(file); continue; }
+
+            if (policy === "seed") {
+                if (exists) { notes.kept.push(file); continue; }
+                write(target, file, theirs, exec);
+                notes.seeded.push(file);
+                continue;
+            }
+            // merge
+            if (!exists) { write(target, file, theirs, exec); notes.written.push(file); continue; }
+            const ours = fs.readFileSync(full, "utf8");
+            if (ours === theirs) continue;                       // already current
+            if (base === null) { notes.kept.push(file); continue; }
+            const from = blob(templateDir, base, file);
+            if (from === null) { notes.kept.push(file); continue; }   // new to the upstream, and the target has its own
+            if (ours === from) { write(target, file, theirs, exec); notes.written.push(file); continue; }
+            const merged = threeWay(from, ours, theirs);
+            if (merged.failed) { notes.kept.push(file); continue; }
+            write(target, file, merged.text, exec);
+            (merged.conflicts ? notes.conflicted : notes.merged).push(file);
+        }
+
+        skeletons(target);
+        mergeSkills(target, templateDir, head, skills);
+
+        if (!dryRun) {
+            fs.writeFileSync(lockPath, JSON.stringify({
+                template: TEMPLATE, ref, commit: head, 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);
+        }
+        report(target, head, ref, base);
+    } finally {
+        if (temporary) fs.rmSync(templateDir, { recursive: true, force: true });
+    }
+}
+
+// Skills merge by name, not by content: the upstream's are added and updated, and a skill the
+// project vendored itself is never removed. skills-lock.json is the union, the project's entry
+// winning where both name the same skill, so a project that pinned a different source keeps it.
+function mergeSkills(target, templateDir, head, files) {
+    const SKILLS = ".agents/skills/";
+    const ours = path.join(target, "skills-lock.json");
+    const theirLock = JSON.parse(blob(templateDir, head, "skills-lock.json") || '{"skills":{}}');
+    const ourLock = fs.existsSync(ours) ? JSON.parse(fs.readFileSync(ours, "utf8")) : { skills: {} };
+    ourLock.skills = ourLock.skills || {};
+
+    const mine = new Set(Object.keys(ourLock.skills));
+    for (const file of files) {
+        if (!file.startsWith(SKILLS)) continue;                 // .claude/skills links are rebuilt, not copied
+        const name = file.slice(SKILLS.length).split("/")[0];
+        // A skill the project installed under a name the upstream also uses stays the project's.
+        if (mine.has(name) && !theirLock.skills[name]) continue;
+        const text = blob(templateDir, head, file);
+        if (text === null) continue;
+        const full = path.join(target, file);
+        const exists = fs.existsSync(full);
+        if (exists && fs.readFileSync(full, "utf8") === text) continue;
+        write(target, file, text);
+        (exists ? notes.merged : notes.written).push(file);
+    }
+    for (const [name, entry] of Object.entries(theirLock.skills)) {
+        if (!ourLock.skills[name]) ourLock.skills[name] = entry;
+    }
+    if (!dryRun) fs.writeFileSync(ours, JSON.stringify(ourLock, null, 2) + "\n");
+}
+
+// Two files nothing copied: the per-harness skill links, which depend on which skills this project
+// has rather than which the upstream ships, and the third-party notice, which must describe this
+// project's lock file. Both are generated, so the install leaves a harness that works rather than a
+// list of commands to remember.
+function finish(target) {
+    for (const [label, args] of [["links", ["relink"]], ["notices", ["notices"]]]) {
+        const r = lib.node([path.join(target, "scripts/skills.js"), ...args], { cwd: target });
+        say(r.status === 0 ? r.output : `${label}: ${r.output}`);
+    }
+}
+
+function report(target, head, ref, base) {
+    const list = (label, arr) => { if (arr.length) say(`\n${label} (${arr.length}):\n  ${arr.sort().join("\n  ")}`); };
+    say("");
+    say(dryRun ? `dry run against ${ref} at ${head.slice(0, 8)}` : `harness updated to ${ref} at ${head.slice(0, 8)}`);
+    if (!base) say("no merge base: this was an install, so nothing that already existed was changed");
+    list("added", notes.written);
+    list("merged", notes.merged);
+    list("created for the first time", notes.seeded);
+    list("left alone, yours", notes.kept.concat(notes.skipped));
+    // Named rather than listed: the fixtures alone are sixty files, and the point is the rule, not
+    // the inventory. Nothing a project runs reaches any of it.
+    if (notes.template.length) {
+        const named = notes.template.filter(f => !f.startsWith(".agents/hooks/tests/"));
+        say(`\nnot installed, the upstream's own (${notes.template.length}): ${named.join(", ")}, and the suite's fixtures`);
+    }
+    if (notes.conflicted.length) {
+        list("CONFLICTED, resolve the markers by hand", notes.conflicted);
+        say(`\nEach one holds <<<<<<< yours / ======= / >>>>>>> upstream (new). Resolve them, then run the suite:\n  node .agents/hooks/test.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`);
+
+    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"}`);
+    }
+    if (notes.conflicted.length || (check && check.failed)) process.exit(1);
+}
+
+main();