infinity-harness 2.0.0 → 2.0.2

package/CHANGELOG.md

@@ -4,6 +4,97 @@ All notable changes to this project are documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.2] — 2026-08-23
+
+Everything here is one bug: the package told people to run commands it does not have. 2.0.1 fixed
+some of them; this fixes the rest, and adds the test that makes the whole class impossible.
+
+### Fixed
+
+- **Every brief ended by telling the model to run a command that does not exist.** The last thing
+  each brief said was `2. Run: harness validate` — a CLI that stopped existing when it was ported
+  into `src/`. The brief is injected at session start and after every phase change; the model read
+  that instruction, ran it, and got "command not found" every single turn. It now names the
+  `infinity_validate` tool, and `/infinity:validate` for the human.
+- **Three phase docs referenced `infinity_status`, which is not a tool.** It is `/infinity:status`.
+- **36 mechanical-rename artefacts across 11 shipped documents** — "Run `the infinity_validate tool`"
+  and friends, in the phase and role docs the brief points the agent at every phase.
+- **`capability-acquisition.md` did not actually get rewritten in 2.0.1.** A `git rm` earlier in the
+  same command failed, `&&` short-circuited, and the heredoc that was supposed to replace the file
+  never ran — so 2.0.1 shipped the old text, still pointing at `infinity-harness capability add …`
+  and at MCP servers pi cannot use. Rewritten, and verified this time.
+- **`cli-design.md` used `infinity-harness init` as its example error message.**
+
+### Added
+
+- **`tests/surface.test.ts`** — the guard for all of it. It parses the tools and commands the
+  extension actually registers, then holds every rendered brief and all 48 shipped documents to that
+  list: no `infinity_*` tool or `/infinity:*` command may be named unless it exists, nothing may
+  point at a command line this package does not have, and the rename artefact cannot come back. The
+  changelog is exempt — its job is to name what a release removed. It found four defects the moment
+  it was written.
+
+---
+
+## [2.0.1] — 2026-08-23
+
+### Fixed
+
+- **pi printed a skill conflict on every start.** `harness/skills/README.md` was a README, and pi
+  loads *every* `.md` in a declared skills directory as a skill — so every session opened with
+  `[Skill conflicts] … description is required`. The README moved to `harness/docs/skills.md`, and
+  `tests/skills.test.ts` now audits the shipped skills against pi's own rules (frontmatter present,
+  `description` non-empty and within length, `name` lowercase-and-hyphens, matching its filename, no
+  duplicates, no UTF-8 BOM hiding the header). A warning the user saw at runtime is a failure we see
+  at test time.
+- **Four shipped skills told the agent to run a CLI that does not exist.**
+  `capability-acquisition`, `building-tools`, `writing-skills` and the deleted MCP skill all
+  instructed the model to register capabilities with `infinity-harness capability add …` — a command
+  from the `dev-harness` ancestor that this package never had. An agent following them got stuck at
+  3am on a command not found. Rewritten around what pi actually provides: a skill file in
+  `.pi/skills/`, a script in the repo, or an extension via `pi install`.
+
+### Removed
+
+- **`building-mcp-servers.md`**, and every other reference to MCP. pi has no MCP client — no
+  dependency, no configuration, no code — so a skill about scaffolding MCP servers and registering
+  them could only send the agent somewhere pi cannot follow. This is a pi extension; MCP was
+  another system's answer.
+- **`harness/capability/sources.json` and `harness/tools/`.** Neither was read by any code, neither
+  was published, and both documented the same missing CLI.
+
+### Added
+
+- **The brief names the skills that match the work.** The docs claimed it did; nothing implemented
+  it. Every skill now declares a `kind` — `process` (belongs to its phase), `domain` (needs to share
+  vocabulary with the task) or `meta` (asked for explicitly) — and the brief ranks them by phase
+  position, tag hits and name mentions, showing the best two. A task about *"two workers racing on
+  the lock"* gets `concurrency-async`; a bare BUILD task gets `tdd`; a task that matches nothing gets
+  no section at all, because a padded section teaches the model to skip it.
+- **`src/core/skills.ts`** — skill loading, header parsing and matching, resolved from the package so
+  it works in an install with no project setup.
+- **`src/core/skillsAudit.ts`** — pi's validation rules, reproduced strictly enough that a clean
+  audit means a clean start. Also catches what pi does not: a duplicate name (pi keys skills by name,
+  so one silently ceases to exist), a mistyped phase, a missing `kind`, and a name that disagrees
+  with its filename.
+- **A `package` E2E scenario** — `npm pack`, extracted and inspected. Every bug it looks for was
+  found by a user after install and by nothing in this repository: a file pi rejects, a symlink out
+  of the tree, a module the extension imports that npm did not publish, a UTF-8 BOM. The repo working
+  tree is not the product; the tarball is.
+- **A reachability guard.** "The tested code was not the shipped code" was this project's worst bug.
+  The `package` scenario now also walks every import from the extension entry point and fails on any
+  *new* module that ships without a path to it. Nine modules are unreachable today — `worker`,
+  `unstuck`, `review`, `rework`, `replan`, the three `goal*` modules and the audit itself — and they
+  are named in the test with the reason, so the debt is visible and cannot grow quietly.
+
+### Changed
+
+- `prototype` now leads with PLAN rather than BUILD — it answers a design question before you commit
+  to one, and the phase a skill leads with is what decides its rank.
+- Tag matching tolerates plurals, so a task about "two workers" matches the `worker` tag.
+
+---
+
 ## [2.0.0] — 2026-08-23
 
 Renamed from `pi-harness` to **infinity-harness**, and rebuilt from a working prototype into
@@ -13,10 +104,10 @@ changed, and the extension no longer depends on an external repository.
 ### Breaking
 
 - **Package renamed** `pi-harness` → `infinity-harness`.
-- **Tools renamed.** `harness_task_list` → `infinity_plan`, `pi_goal_task`/`harness_goal_loop` →
-  `infinity_goal`, `pi_harness_remote`/`harness_remote` → `infinity_dashboard`,
-  `harness_spawn_worker` → `infinity_spawn_worker`. New: `infinity_brief`, `infinity_validate`,
-  `infinity_advance`.
+- **Tools renamed.** `harness_task_list` → `infinity_plan`, `pi_harness_remote`/`harness_remote` →
+  `infinity_dashboard`. New: `infinity_brief`, `infinity_validate`, `infinity_advance`. The goal-loop
+  and worker-spawn tools were not carried over — their modules ship but nothing registers them (see
+  the reachability guard in the `package` E2E scenario).
 - **Commands renamed** to the `/infinity:*` namespace, and `/infinity:run` / `/infinity:halt` added.
 - **The `cli`, `prompts` and `skills` symlinks are gone.** They pointed at absolute paths inside a
   sibling `dev-harness` checkout, which made the package impossible to install anywhere else. The

package/README.md

@@ -186,6 +186,32 @@ verdict. It refreshes itself every 5 seconds and reconnects with backoff if the
 The dashboard is strictly read-only and binds to `127.0.0.1`. It never writes, and never bumps
 `baseRevision` — opening it can't perturb the run you're watching.
 
+## Craft skills
+
+28 short documents on how to do the work well — how to write a test worth
+keeping, how to debug something intermittent, how to design a module boundary.
+They ship with the package, so pi loads them wherever it's installed and the
+model can invoke any of them by name.
+
+A model with 28 skills available and no idea which one applies reads none of
+them, so **the brief names the ones that match the work in hand**. Each skill
+declares what it's for:
+
+```yaml
+kind: domain                                     # process | domain | meta
+phases: [plan, build, verify]                    # the phase it leads counts most
+tags: [concurrency, race, lock, mutex, deadlock] # vocabulary a task would use
+```
+
+A `process` skill belongs to its phase — TDD is the right answer for a BUILD
+task whatever the task says. A `domain` skill has to share vocabulary with the
+task: nobody needs the database skill because they happen to be in BUILD. So a
+task called *"serialise plan writes so two workers can't race on the lock"*
+gets `concurrency-async`, and a bare BUILD task gets `tdd`.
+
+When nothing matches, the brief has no skills section. An empty section is
+honest; a padded one teaches the model to skip it.
+
 ## Model routing (optional)
 
 Send cheap tasks to a small model and hard ones to a large one. Pick them with `/infinity:config` →
@@ -229,6 +255,7 @@ infinity-harness/
 ├── src/
 │   ├── core/                      types · paths · fsx · config · phases · gates · brief
 │   │                              · featureList (the SSOT) · lock · exec
+│   │                              · skills (match) · skillsAudit (guard)
 │   ├── ui/                        theme · widget (terminal) · dashboard (web)
 │   ├── loop.ts                    the continuous-run driver and its stop conditions
 │   ├── taskList.ts                atomic plan editor
@@ -242,8 +269,8 @@ infinity-harness/
 │   ├── config.json                pipeline state and settings
 │   ├── model-router.json          optional routing
 │   ├── docs/                      architecture · decisions · phase and role docs
-│   └── skills/                    29 craft skills the brief points at
-├── tests/                         20 files, plain node:assert
+│   └── skills/                    28 craft skills the brief points at
+├── tests/                         23 files, plain node:assert
 └── scripts/run-tests.mjs
 ```
 
@@ -255,7 +282,7 @@ there is one implementation, and the adapter calls it.
 ```bash
 npm install
 npm run check    # tsc --noEmit
-npm test         # 20 test files
+npm test         # 23 test files
 npm run e2e      # end-to-end against a live model
 ```
 

package/harness/docs/ARCHITECTURE.md

@@ -153,7 +153,7 @@ Every stop carries a reason. A human coming back finds an explanation, not a mys
 ## Verification
 
 - `npm test` — 20 unit files, plain `node:assert`, no framework.
-- `npm run e2e` — 11 scenarios over real temp projects, real git repos, real child processes: the
+- `npm run e2e` — 12 scenarios over real temp projects, real git repos, real child processes: the
   full pipeline walkthrough, loop convergence, every stop condition, SIGKILL-and-restart, a 6-way
   concurrent write fan-out with an unlocked control, data round-trip, the dashboard, widget
   rendering across shapes, adversarial input, and the extension adapter itself.

package/harness/docs/agents/generator.md

@@ -10,4 +10,4 @@ You implement. You produce artifacts. You self-check.
 - In BUILD: implement ONE task at a time, then validate
 - In VERIFY: run the full test suite
 - In SIMPLIFY: adopt the Simplifier persona (see simplifier.md)
-- When done: call `the infinity_validate tool`
+- When done: call `infinity_validate`

package/harness/docs/agents/simplifier.md

@@ -10,4 +10,4 @@ You refactor. You clean. You never change behavior.
 - Break long functions (~40 line threshold)
 - Rename unclear variables
 - ⚠ All tests must still pass after your changes
-- Run `the infinity_validate tool` after each feature to confirm gate
+- Run `infinity_validate` after each feature to confirm gate

package/harness/docs/phases/build.md

@@ -15,16 +15,16 @@ producing instructions for each. Validate after each task before advancing.
 
 ## Process
 1. Read `harness/progress.md`, `AGENTS.md`, and `harness/features/feature-list.json`
-2. Run `the infinity_brief tool` to get the current task brief (feature, task, criteria)
+2. Run `infinity_brief` to get the current task brief (feature, task, criteria)
 3. For each incomplete feature → for each pending task:
    a. Implement the task **test-first** (see `harness/skills/tdd.md`): failing
       test → minimal code to pass → next slice
-   b. Run `the infinity_validate tool --feature <id> --task <id>` to validate
+   b. Run `infinity_validate` with `{feature, task}` to validate
    c. If PASS → task marked complete, advance to next task
    d. If FAIL → fix issues, re-validate (retry up to `retry.tasks.maxRetries`)
 4. When all tasks in a feature pass → feature marked complete
 5. When all features pass → phase gate passes
-6. Run `the infinity_advance tool` to advance to VERIFY
+6. Run `infinity_advance` to advance to VERIFY
 
 ## Rationalizations to Avoid
 | Excuse | Rebuttal |
@@ -39,9 +39,9 @@ producing instructions for each. Validate after each task before advancing.
 - Tests that only test the implementation, not the behavior
 
 ## Verification
-- [ ] Each task validated with `the infinity_validate tool --feature X --task Y`
+- [ ] Each task validated with `infinity_validate` scoped to that feature and task
 - [ ] All features marked `passes: true` in feature-list.json
-- [ ] `the infinity_validate tool` passes (full phase gates)
+- [ ] `infinity_validate` passes (full phase gates)
 
 ## Handoff
-On gate pass: `the infinity_advance tool` (Generator → Evaluator for VERIFY)
+On gate pass: `infinity_advance` (Generator → Evaluator for VERIFY)

package/harness/docs/phases/define.md

@@ -33,8 +33,8 @@ feature list.
      these criteria really prove the sprint worked?)
 8. **Create a feature branch**: `git checkout -b feature/<short-slug>` (the
    gate rejects work on main/master)
-9. Run `the infinity_validate tool` to check gates
-10. If PASS → `the infinity_advance tool` to advance to PLAN
+9. Run `infinity_validate` to check gates
+10. If PASS → `infinity_advance` to advance to PLAN
 
 ## Rationalizations to Avoid
 | Excuse | Rebuttal |
@@ -52,7 +52,7 @@ feature list.
 - [ ] Sprint contract agreed with non-placeholder verification criteria
 - [ ] On a feature branch (not main/master)
 - [ ] Folder structure agreed and documented
-- [ ] `the infinity_validate tool` passes
+- [ ] `infinity_validate` passes
 
 ## Handoff
-On gate pass: `the infinity_advance tool` (Planner → continues as Planner for PLAN)
+On gate pass: `infinity_advance` (Planner → continues as Planner for PLAN)

package/harness/docs/phases/plan.md

@@ -23,8 +23,8 @@ a unit of work that BUILD can implement and VERIFY can validate independently.
    needs `definitionOfDone` (user-visible outcomes). Gates reject
    placeholders.
 5. Commit the plan (`git commit -am "plan: feature list"`)
-6. Run `the infinity_validate tool` to check gates
-7. If PASS → `the infinity_advance tool` to advance to BUILD
+6. Run `infinity_validate` to check gates
+7. If PASS → `infinity_advance` to advance to BUILD
 
 > The sprint contract was agreed in DEFINE. If PLAN reveals the scope was
 > wrong, renegotiate it now (`contract propose` → `contract review`) — not
@@ -44,7 +44,7 @@ a unit of work that BUILD can implement and VERIFY can validate independently.
 ## Verification
 - [ ] `feature-list.json` exists with features and tasks
 - [ ] Sprint contract proposed and agreed
-- [ ] `the infinity_validate tool` passes
+- [ ] `infinity_validate` passes
 
 ## Handoff
-On gate pass: `the infinity_advance tool` (Planner → Generator for BUILD)
+On gate pass: `infinity_advance` (Planner → Generator for BUILD)

package/harness/docs/phases/review.md

@@ -14,7 +14,7 @@ up-to-date with upstream.
 
 ## Process
 1. Read `harness/progress.md`, `AGENTS.md`, and `harness/evaluator-rubric.md`
-2. Run `the infinity_status command` to see current state
+2. Run `/infinity:status` to see current state
 3. Run the two-axis review from `harness/skills/code-review.md`:
    spec axis (against `specs/prd.md` + sprint contract + acceptance criteria)
    and standards axis (repo conventions + smell baseline). Fix what's real.
@@ -22,8 +22,8 @@ up-to-date with upstream.
    - Architecture, test coverage, code quality, documentation, performance, security
 5. Check documentation: README.md, CHANGELOG.md, architecture docs
 6. Ensure branch is up-to-date: `git push` if needed
-7. Run `the infinity_validate tool` to check gates
-8. If PASS → `the infinity_advance tool` to advance to SHIP
+7. Run `infinity_validate` to check gates
+8. If PASS → `infinity_advance` to advance to SHIP
 
 ## Rationalizations to Avoid
 | Excuse | Rebuttal |
@@ -41,7 +41,7 @@ up-to-date with upstream.
 - [ ] Evaluator rubric score >= 8/12
 - [ ] README.md, CHANGELOG.md exist and are current
 - [ ] Branch up-to-date with upstream
-- [ ] `the infinity_validate tool` passes
+- [ ] `infinity_validate` passes
 
 ## Handoff
-On gate pass: `the infinity_advance tool` (Evaluator → Generator for SHIP)
+On gate pass: `infinity_advance` (Evaluator → Generator for SHIP)

package/harness/docs/phases/ship.md

@@ -10,13 +10,13 @@ clean working tree, and ensure all ship gates pass.
 
 ## Process
 1. Read `harness/progress.md` and `AGENTS.md`
-2. Run `the infinity_status command` to see current state
+2. Run `/infinity:status` to see current state
 3. Finalize `CHANGELOG.md` with version, date, and changes
 4. Verify working tree is clean: `git status`
 5. Create version tag: `git tag v<version>`
 6. Ensure LICENSE, CONTRIBUTING.md exist
-7. Run `the infinity_validate tool` to check ship gates
-8. If PASS → `the infinity_advance tool` (pipeline complete!)
+7. Run `infinity_validate` to check ship gates
+8. If PASS → `infinity_advance` (pipeline complete!)
 9. Create checkpoint: `infinity-harness checkpoint create release-<version>`
 
 ## Rationalizations to Avoid
@@ -37,7 +37,7 @@ clean working tree, and ensure all ship gates pass.
 - [ ] Version tag created: `git tag -l "v*"`
 - [ ] CHANGELOG.md updated with version + changes
 - [ ] README.md, LICENSE, CONTRIBUTING.md exist
-- [ ] `the infinity_validate tool` passes
+- [ ] `infinity_validate` passes
 
 ## Handoff
-On gate pass: Pipeline complete! `the infinity_status command` shows "Pipeline complete".
+On gate pass: Pipeline complete! `/infinity:status` shows "Pipeline complete".

package/harness/docs/phases/simplify.md

@@ -14,14 +14,14 @@ duplicates, flatten deep nesting, and ensure tests still pass after changes.
 
 ## Process
 1. Read `harness/progress.md` and `AGENTS.md`
-2. Run `the infinity_brief tool` to see the current step
+2. Run `infinity_brief` to see the current step
 3. For each feature:
    a. Review code for: code smells, deep nesting, DRY violations, dead code
    b. Simplify: consolidate duplicate logic, flatten conditionals, remove unused
    c. Run `npm test` to ensure tests still pass after simplification
-   d. Run `the infinity_validate tool --feature <id> --task <id>` per task
-4. When all features simplified → run `the infinity_validate tool` (full phase)
-5. If PASS → `the infinity_advance tool` to advance to REVIEW
+   d. Run `infinity_validate` with `{feature, task}` per task
+4. When all features simplified → run `infinity_validate` (full phase)
+5. If PASS → `infinity_advance` to advance to REVIEW
 
 ## Rationalizations to Avoid
 | Excuse | Rebuttal |
@@ -39,7 +39,7 @@ duplicates, flatten deep nesting, and ensure tests still pass after changes.
 - [ ] Code smells reduced (subjective — use judgment)
 - [ ] No new dead code introduced
 - [ ] Tests still pass: `npm test`
-- [ ] `the infinity_validate tool` passes
+- [ ] `infinity_validate` passes
 
 ## Handoff
-On gate pass: `the infinity_advance tool` (Simplifier → Evaluator for REVIEW)
+On gate pass: `infinity_advance` (Simplifier → Evaluator for REVIEW)

package/harness/docs/phases/verify.md

@@ -14,15 +14,15 @@ role runs tests, checks coverage, and validates behavior against the PRD.
 
 ## Process
 1. Read `harness/progress.md`, `AGENTS.md`, and `specs/prd.md`
-2. Run `the infinity_brief tool` to see the current verification step
+2. Run `infinity_brief` to see the current verification step
 3. For each feature:
    a. Run the test suite: `npm test`
    b. Check coverage: `{{coverageCmd}}` (if coverage gate enabled)
    c. Verify behavior matches acceptance criteria from PRD
-   d. Run `the infinity_validate tool --feature <id> --task <id>` per task
+   d. Run `infinity_validate` with `{feature, task}` per task
 4. If any task fails → fix and re-validate (retry)
-5. When all features verified → run `the infinity_validate tool` (full phase)
-6. If PASS → `the infinity_advance tool` to advance to SIMPLIFY or REVIEW
+5. When all features verified → run `infinity_validate` (full phase)
+6. If PASS → `infinity_advance` to advance to SIMPLIFY or REVIEW
 
 ## Rationalizations to Avoid
 | Excuse | Rebuttal |
@@ -40,7 +40,7 @@ role runs tests, checks coverage, and validates behavior against the PRD.
 - [ ] All tests pass: `npm test`
 - [ ] Coverage meets threshold (if gate enabled)
 - [ ] Behavior matches PRD acceptance criteria
-- [ ] `the infinity_validate tool` passes
+- [ ] `infinity_validate` passes
 
 ## Handoff
-On gate pass: `the infinity_advance tool` (Evaluator → Simplifier for SIMPLIFY, or Evaluator for REVIEW)
+On gate pass: `infinity_advance` (Evaluator → Simplifier for SIMPLIFY, or Evaluator for REVIEW)

package/harness/docs/skills.md

@@ -0,0 +1,89 @@
+<!--
+Kept in docs/, not in harness/skills/.
+
+pi loads every .md in a declared skills directory as a skill and requires
+`name` and `description` frontmatter on each. A README has neither, so leaving
+it beside the skills made pi print a skill conflict on every start.
+`tests/skills.test.ts` now fails if anything in harness/skills/ would do that.
+-->
+
+# Craft Skills
+
+How to do the work WELL — the engineering discipline behind each pipeline
+phase. The phase docs (`harness/docs/phases/`) say *what* to produce; these
+skills say *how* an expert produces it.
+
+They ship with the package, so pi loads them wherever it is installed: the
+model can invoke any of them by name, and `/skill:<name>` lists them.
+
+**The brief names the ones that match the work in hand.** Each skill declares
+what it is for, so the brief can route:
+
+```yaml
+kind: domain                                    # process | domain | meta
+phases: [plan, build, verify]                   # leading phase counts most
+tags: [concurrency, race, lock, mutex, deadlock] # vocabulary a task would use
+```
+
+- **`process`** — how to work in a phase. Belonging to the phase is enough;
+  TDD is the right answer for a BUILD task whatever the task says.
+- **`domain`** — a subject area. Surfaces only when the task shares its
+  vocabulary. Nobody needs the database skill for being in BUILD.
+- **`meta`** — growing the toolkit. Vocabulary only, never a phase.
+
+Read the one the brief names before you start. Each is short, and it changes
+what you do.
+
+## Process skills
+
+| Skill | Leads | One-liner |
+|-------|-------|-----------|
+| `grilling.md` | DEFINE | Stress-test the spec with relentless questions |
+| `domain-modeling.md` | DEFINE | Pin down domain terms before writing code |
+| `research.md` | DEFINE | Answer questions from primary sources only |
+| `planning-tasks.md` | PLAN | Break specs into tracer-bullet vertical slices |
+| `codebase-design.md` | PLAN | Design deep modules behind small interfaces |
+| `prototype.md` | PLAN | Throwaway code that answers a design question |
+| `tdd.md` | BUILD | Red → green loop; tests worth keeping |
+| `self-review.md` | BUILD | The pass that runs before every validate |
+| `diagnosing-bugs.md` | VERIFY | Build a feedback loop before hypothesising |
+| `code-review.md` | REVIEW | Two-axis review: standards + spec |
+| `resolving-merge-conflicts.md` | any | Resolve conflicts by original intent |
+| `context-hygiene.md` | any | Externalise discoveries the moment they happen |
+| `scope-discipline.md` | any | The contract is the boundary; park everything else |
+| `stuck-protocol.md` | any | Stop thrashing, escalate cleanly |
+
+## Domain skills
+
+Matched by vocabulary, not by phase:
+
+`databases` · `http-apis` · `auth-security` · `frontend-ui` ·
+`testing-infra` · `concurrency-async` · `performance` ·
+`error-handling-logging` · `config-and-secrets` · `cli-design` ·
+`pi-todo-adapted`
+
+## Meta skills
+
+| Skill | Purpose |
+|-------|---------|
+| `capability-acquisition.md` | HAVE → ACQUIRE → CREATE → KEEP |
+| `writing-skills.md` | How to author a skill worth keeping |
+| `building-tools.md` | Standards for a project script anyone can run |
+
+Growing the library is part of the job. A skill you write into
+`.pi/skills/<name>.md` is loaded by pi on the next start — there is nothing to
+register — and committing it means the next session starts one rung higher.
+
+## Adding one here
+
+Frontmatter is a strict subset: `key: value`, `key: [a, b]`, `key: { k: v }`.
+No block scalars, no multi-line values. `name` must match the filename, be
+lowercase `a-z0-9-`, and `description`, `kind` and `phases` must all be
+present and valid — `npm test` enforces every one of those, because pi only
+warns and it warns on every single start.
+
+## Attribution
+
+Skills marked "Adapted from mattpocock/skills" derive from
+[Matt Pocock's skills repository](https://github.com/mattpocock/skills)
+(MIT License, © 2026 Matt Pocock), adapted for the infinity-harness pipeline.

package/harness/skills/auth-security.md

@@ -4,6 +4,7 @@ description: Authentication, authorization, secrets, and the injection/XSS/CSRF
 tags: [auth, authentication, authorization, security, login, password, token, jwt, session, oauth, secret, csrf, xss, injection, permission]
 when: task touches login, sessions, tokens, permissions, user input, or secrets
 phases: [plan, build, verify]
+kind: domain
 provenance: { origin: built-in }
 ---
 

package/harness/skills/building-tools.md

@@ -1,60 +1,56 @@
 ---
 name: building-tools
-description: Project tool standards — idempotent, self-documenting, non-interactive executables
-tags: [meta, tool, script, cli, automation, executable]
-when: a repeatable action deserves a registered executable instead of ad-hoc shell
+description: Project script standards — idempotent, self-documenting, non-interactive executables
+tags: [meta, tool, script, cli, automation, executable, makefile]
+when: a repeatable action deserves a script instead of the same shell dance twice
 phases: []
+kind: meta
 provenance: { origin: built-in }
 ---
 
 # Building Tools
 
-A tool is a registered executable under `harness/tools/` that future
-sessions (and other agents) can find and run. Build one when you catch
-yourself doing the same multi-step shell dance twice.
+Build one when you catch yourself doing the same multi-step shell dance
+twice. The bar is not "it worked once on my machine" — an unattended agent
+will run this at 3am with no one watching.
 
-## Process
+There is nothing to register. A script in the repo, named in `AGENTS.md` or
+`package.json`, is discoverable by the next session; a script nobody can
+find is a script nobody runs.
 
-1. `infinity-harness capability create tool <name>` → stub at
-   `harness/tools/<name>.sh` (any language works — .mjs, .py; the stub is
-   bash).
-2. Implement to the standards below.
-3. Register:
-
-   ```
-   infinity-harness capability add tool harness/tools/<name>.sh \
-     --run "bash harness/tools/<name>.sh" \
-     --tags db,fixtures --description "Reset local db to fixtures"
-   ```
-
-## Standards (the registration bar)
+## Standards
 
 - **Idempotent** — running it twice is safe and converges to the same state.
-- **`--help` works** — prints usage + purpose, exits 0. (`capability
-  doctor` checks exactly this.)
-- **`--json` where output is consumed** — machine-readable when another
-  tool or agent reads the result.
-- **Exit codes:** 0 success · 1 operation failed · 2 usage error.
-- **Never interactive** — no prompts, no confirmations; flags only. An
-  unattended agent runs this at 3am.
-- **Fail loud and specific** — errors name the thing that's wrong and the
-  likely fix, on stderr.
-- **Self-contained** — resolve paths relative to the project root, not the
-  caller's cwd.
+- **`--help` works** — prints usage and purpose, exits 0. This is the first
+  thing anyone runs, human or model.
+- **`--json` where output is consumed** — machine-readable when something
+  downstream reads the result. Humans get the summary line.
+- **Exit codes** — `0` success · `1` the operation failed · `2` you were
+  called wrong. An agent branches on these; get them right.
+- **Never interactive** — no prompts, no confirmations, no "are you sure".
+  Flags only.
+- **Fail loud and specific** — errors name the thing that is wrong and the
+  likely fix, on stderr. "Error: 1" costs someone an hour.
+- **Self-contained** — resolve paths from the project root, not the
+  caller's cwd. Check prerequisites at startup and fail with the install
+  command.
 
 ## Anti-patterns
 
-- **The snowflake** — works only on the author's machine (hardcoded paths,
-  undeclared deps). Fix: check prerequisites at startup, fail with install
+- **The snowflake** — hardcoded paths, undeclared dependencies, works only
+  where it was written. Fix: check prerequisites first, fail with
   instructions.
 - **The chatterbox** — pages of output hiding the result. Fix: one summary
   line by default, `--verbose` for the rest.
-- **The mutation surprise** — destructive with no dry-run. Fix: anything
-  destructive gets `--dry-run` and defaults to showing what it would do.
+- **The mutation surprise** — destructive with no dry run. Fix: anything
+  destructive gets `--dry-run`, and says what it would do.
+- **The second source of truth** — a script that keeps its own copy of state
+  the project already stores. Fix: read the real file.
 
 ## Checklist
 
-- [ ] Idempotent (ran it twice to prove it)
-- [ ] `--help` exit 0; exit codes correct
-- [ ] Registered with ≥2 tags + description
-- [ ] `infinity-harness capability doctor --type tool` passes
+- [ ] Ran it twice; the second run was a no-op
+- [ ] `--help` exits 0 and explains the purpose
+- [ ] Exit codes are 0 / 1 / 2 and mean what they should
+- [ ] No prompt, no confirmation, no TTY assumption
+- [ ] Named somewhere a cold reader will find it