infinity-harness 2.0.1 → 2.0.3

package/CHANGELOG.md

@@ -4,6 +4,50 @@ 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.3] — 2026-08-23
+
+### Fixed
+
+- **`npm test` failed in any project that had actually been used.** The surface guard added in 2.0.2
+  walked the filesystem for documents to check, so it also read the files the harness *writes* —
+  `harness/session-handoff.md`, `harness/.run-prompt.md` — which are git-ignored scratch carrying
+  whatever commands were current when they were generated. It now asks git what the repository
+  ships. A test that fails because you ran the tool is a test people turn off.
+
+---
+
+## [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
@@ -72,10 +116,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

@@ -270,7 +270,7 @@ infinity-harness/
 │   ├── model-router.json          optional routing
 │   ├── docs/                      architecture · decisions · phase and role docs
 │   └── skills/                    28 craft skills the brief points at
-├── tests/                         22 files, plain node:assert
+├── tests/                         23 files, plain node:assert
 └── scripts/run-tests.mjs
 ```
 
@@ -282,7 +282,7 @@ there is one implementation, and the adapter calls it.
 ```bash
 npm install
 npm run check    # tsc --noEmit
-npm test         # 22 test files
+npm test         # 23 test files
 npm run e2e      # end-to-end against a live model
 ```
 

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/skills/capability-acquisition.md

@@ -1,8 +1,8 @@
 ---
 name: capability-acquisition
-description: The capability ladder — HAVE, ACQUIRE, CREATE, KEEP — for skills, MCP servers, and tools
-tags: [meta, capability, acquire, search, skill, mcp, tool, ladder, library]
-when: a task needs knowledge, system access, or an executable the project lacks
+description: The capability ladder — HAVE, ACQUIRE, CREATE, KEEP — for skills, extensions and project scripts
+tags: [meta, capability, acquire, search, skill, extension, tool, script, ladder, library]
+when: a task needs knowledge, an integration, or an executable the project lacks
 phases: []
 kind: meta
 provenance: { origin: built-in }
@@ -10,64 +10,66 @@ provenance: { origin: built-in }
 
 # Capability Acquisition — The Ladder
 
-Your task needs something the library lacks. Resolve it with the ladder —
-and register what you find so the NEXT task starts at Tier 0.
+The task needs something you do not have. Work the ladder in order, and leave
+the result behind so the next task starts one rung higher.
 
-## Step 1 — Decide the capability TYPE
+pi has three kinds of capability. Pick the right shape first — most wasted
+effort here is building the wrong one.
 
-- Need **knowledge or method** (how to do X well) → a **skill**
-- Need to **interact with an external system** (DB, API, browser, tracker) → an **MCP server**
-- Need a **repeatable executable action** (reset fixtures, run a codemod) → a **tool**
-- Need a **fact** (does API X support Y?) → follow `research.md` — findings
-  saved under `docs/research/` with frontmatter become matchable facts
+| You need | Build | Lives in |
+|---|---|---|
+| Knowledge or method — how to do X well | a **skill** | `.pi/skills/<name>.md` |
+| A repeatable action — reset fixtures, run a codemod | a **script** | the repo, run through bash |
+| A tool the model can call, or a slash command | an **extension** | its own package, `pi install`ed |
+| A fact — does API X support Y? | neither | `research.md`, written into `harness/docs/` |
 
-## Step 2 — ACQUIRE: search the sources
+## 1 — HAVE: check before you build
 
-```
-the capability index "<2-4 keywords>" --type skill|mcp|tool
-```
+- **Skills already loaded.** This package ships 28. The brief names the ones
+  that match the current task; `/skill:<name>` invokes any of them.
+- **Scripts already in the repo.** `package.json` scripts, `Makefile`,
+  `scripts/`. Read before you write — the thing you are about to build is
+  often already there under a name you did not guess.
+- **Extensions already installed.** `pi list`.
 
-This queries the machine-queryable registries directly (npm, MCP registry,
-GitHub, crates, …). Browse-only sources are listed after — use them only
-if you have web access.
+## 2 — ACQUIRE: take what exists
 
-**Choosing among hits** (in order): trust tier (official > curated >
-community) → actively maintained → widely used → known author →
-permissive license (MIT/Apache/BSD) → small and composable. NEVER adopt a
-framework that wants to own your whole process — the harness owns the
-process.
+- **A skill** is plain markdown. Copy one in, then *adapt* it: trim to the
+  useful core, re-point its references at this project's surfaces, and add an
+  attribution line naming the source and its licence.
+- **An extension**: `pi install npm:<pkg> -l` (project-local, so the team gets
+  it through `.pi/settings.json`) or `pi install git:<host>/<repo>`. Pin the
+  version, and read what it registers before you trust it.
 
-**Adapt, don't adopt.** Whatever you take: trim it to the useful core,
-re-point references to harness surfaces (DOMAIN.md, feature-list,
-learn/decision), add an attribution line (source + license), then register:
+**Choosing among candidates**, in order: actively maintained → widely used →
+permissive licence (MIT/Apache/BSD) → small and composable. Never adopt
+something that wants to own the whole process — the harness owns the process.
 
-```
-infinity-harness capability add skill <path> --from <url>
-infinity-harness capability add mcp <name> --command npx --args -y,<pkg>@<exact-version> \
-  --tags ... --description "..." --trust curated
-infinity-harness capability add tool <file> --run "..." --tags ... --description "..."
-```
+## 3 — CREATE: nothing usable exists
 
-**MCP security (hard rules):** pin exact versions (`pkg@1.2.3`, never
-`@latest`); community-tier servers need `--force` after you review their
-source; secrets go through env indirection, never into configs.
+- **A skill** → write it per `writing-skills.md` into `.pi/skills/<name>.md`.
+  pi loads it on the next start. There is nothing to register.
+- **A script** → build it per `building-tools.md`, and name it where a cold
+  reader will look (`AGENTS.md`, or `package.json` scripts).
+- **An extension** → only when the capability has to be a tool the model calls
+  or a slash command. It is a package with a `pi.extensions` entry;
+  `pi install ./<dir> -l` loads it straight from a checkout.
 
-## Step 3 — CREATE: nothing usable exists
+## 4 — KEEP: or you will do this again
 
-```
-infinity-harness capability create skill|tool|mcp <name>
-```
+A capability that lives only in this session is not a capability.
 
-- skill → fill the stub per `writing-skills.md`
-- tool → implement per `building-tools.md`
-- mcp → the scaffold is a WORKING server; fill in handlers per
-  `building-mcp-servers.md`, verify with its self-test, then register
+- **Commit it.** A skill in `.pi/skills/` and a script in the repo both travel
+  with the project.
+- **Make it findable.** Tags in a skill's frontmatter are how the brief
+  surfaces it later; a script nobody can find is a script nobody runs.
 
-## Step 4 — Budget and fallback (never block the pipeline)
+## 5 — Budget: never block the pipeline
 
-Acquisition fits ONE working session. If the search didn't conclude, or you
+Acquisition fits inside one working session. If it does not conclude, or you
 have no network:
 
-1. Record the gap: `harness/lessons-decisions.md "capability gap: <what was needed>"`
-2. Proceed with general best practices — a missing skill is not a blocked task
-3. The gap resurfaces via `infinity-harness capability gaps` for a later pass
+1. Record the gap in `harness/lessons-decisions.md` — what was needed, what
+   you tried, what you would try next.
+2. Carry on with general best practice. A missing skill is not a blocked task,
+   and it is never a reason to mark work complete that is not.

package/harness/skills/cli-design.md

@@ -31,9 +31,8 @@ provenance: { origin: built-in }
   consistently; flags kebab-case with `--long` forms; `-` means stdin/
   stdout where files are expected; respect `NO_COLOR` and non-TTY (no
   spinners into pipes).
-- **Errors say what + why + what next:** `✗ config not found:
-  harness/config.json — run: infinity-harness init`. Never a bare stack trace
-  for an expected failure.
+- **Errors say what + why + what next:** `✗ config not found: ./app.config.json
+  — run: myapp init`. Never a bare stack trace for an expected failure.
 - **Fast startup matters.** A CLI invoked in loops pays its startup cost
   ×N — lazy-load heavy imports per subcommand.
 

package/harness/skills/resolving-merge-conflicts.md

@@ -24,7 +24,7 @@ provenance: { origin: "mattpocock/skills", license: MIT, adapted: true }
    trade-off. Do **not** invent new behaviour. Always resolve; never
    `--abort`.
 4. **Run the project's automated checks** — typecheck, then tests, then
-   lint (`the infinity_validate tool` runs the configured set). Fix anything the
+   lint (`infinity_validate` runs the configured set). Fix anything the
    merge broke.
 5. **Finish the merge/rebase.** Stage everything and commit. If rebasing,
    continue until all commits are rebased. Record anything surprising:

package/harness/skills/stuck-protocol.md

@@ -29,7 +29,7 @@ catch any of these tells:
    what you're trying to achieve, the exact error/failure, the attempts
    made, and what each attempt ruled out. Writing this usually exposes the
    gap — half the time you solve it here.
-2. **Re-read the brief and the skill** (`the infinity_brief tool`; the skill it
+2. **Re-read the brief and the skill** (`infinity_brief`; the skill it
    references). Stuck often means a constraint was missed, not that the
    problem is hard.
 3. **Reframe ONCE** — one genuinely different angle, not a variation:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "infinity-harness",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "description": "A pi agent extension that runs a gated build pipeline unattended \u2014 enforces phases, validates with deterministic gates, and keeps working for hours or days without losing the plan.",
   "type": "module",
   "keywords": [

package/src/core/brief.ts

@@ -24,6 +24,16 @@ import * as P from "./paths.ts";
 import { readText } from "./fsx.ts";
 import { loadSkills, matchSkills } from "./skills.ts";
 
+/**
+ * What the agent calls to have its work judged.
+ *
+ * This said `harness validate` for a long time — a command line that has not
+ * existed since the CLI was ported into `src/`. A brief that ends by telling
+ * the model to run a command that does not exist is a brief that ends in a
+ * failed shell call and a confused retry, every single turn.
+ */
+const VALIDATE_TOOL = "infinity_validate";
+
 /**
  * Two is the number that gets read. One hides a better match; five is a
  * reading list, and a reading list is a thing you skip.
@@ -95,7 +105,7 @@ export async function buildBrief(targetDir: string, options: BuildBriefOptions =
         }
       : null,
     criteria: collectCriteria(feature, nextTask?.criteria),
-    validateCommand: "harness validate",
+    validateCommand: VALIDATE_TOOL,
     gate,
     progress: {
       tasksDone: progress.tasksDone,
@@ -252,7 +262,7 @@ export function renderBrief(brief: Brief, config?: HarnessConfig): string {
   L.push("");
   L.push("THE LOOP");
   L.push("  1. Do the work described above.");
-  L.push(`  2. Run: ${brief.validateCommand}`);
+  L.push(`  2. Call the ${brief.validateCommand} tool (a human types /infinity:validate).`);
   L.push("  3. FAIL → fix the listed checks and validate again.");
   L.push("  4. PASS → the harness advances the phase and issues the next brief.");
   L.push("");