infinity-harness 2.0.4 → 2.2.0

package/CHANGELOG.md

@@ -4,6 +4,117 @@ 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.2.0] — 2026-08-23
+
+Nine modules shipped in this package, typechecked, and passed their tests while no code path in the
+running product could reach a single one — about 2,800 lines, advertised in the README. They are all
+connected now, and connecting them found four reasons the most important of them had never worked.
+
+### Added
+
+- **The escalation ladder actually escalates.** `unstuck.ts` could always *choose* what to do when a
+  run stalled — retry → reframe → consult → rework → replan → master, with budgets, fingerprint
+  dedup and a cooldown — and nothing ever executed one. It was a chooser with no actuator, so
+  `/infinity:run` did the only thing it could when the gate kept failing: count three strikes and
+  stop. `src/escalate.ts` is the actuator. On a stall it climbs a rung, does the part that is ours
+  (flipping tasks to `rework`, naming the model to escalate to) and hands the agent an instruction
+  for the part that is the agent's. Every rung says something different; a run that gives up now
+  names every rung it spent first.
+- **The goal loop turns.** `goalSpec`, `goalLoop` and `goalState` are a complete outer loop that
+  nothing ever drove, which meant the harness could finish a pipeline and declare "complete" without
+  anyone asking whether the thing the human asked for was done. `src/goal.ts` drives it, and the
+  mapping is the design: **one goal iteration is one full pass of the pipeline.** `/infinity:goal
+  <what you want>` states it; when the pipeline finishes, the run asks whether the GOAL is met, not
+  whether the plan is. A verdict of anything but `complete` must name what is still missing, and the
+  pipeline rewinds to the first phase with that list carried into the brief — so the next pass plans
+  for the remainder instead of rebuilding what the last review already accepted.
+- **Five tools and three commands** for what was previously unreachable: `infinity_unstuck`,
+  `infinity_rework`, `infinity_replan`, `infinity_spawn_worker`, `infinity_goal`, and
+  `/infinity:goal`, `/infinity:unstuck`, `/infinity:rework`.
+- **A `skills-load` advisory gate check.** The skills audit was the ninth orphan. It now runs at
+  DEFINE and REVIEW over any skills a project ships, so a project finds out that pi will print a
+  `[Skill conflicts]` block before its users do. Advisory: a malformed skill does not make the code
+  wrong.
+- **The widget shows which pass you are on and the last rung taken.** A second pass at a goal looks
+  identical to a first one in every other part of the display, which is exactly when someone glances
+  at a half-full progress bar and walks away thinking it is nearly done.
+- **Two E2E scenarios** — `escalation` and `goal` — driving both through the real adapter over real
+  projects, and the reachability allowlist in the `package` scenario is now **empty**.
+
+### Fixed
+
+Wiring the ladder in exposed why it had never worked, none of which its own passing tests could see:
+
+- **`reframe` had no budget**, so it was eligible forever and shadowed every rung below it. The
+  ladder could not climb past rung two — `consult`, `rework`, `replan` and `master` were unreachable
+  through the function whose job was to reach them.
+- **`rework` and `replan` were vetoed unless the working tree had moved.** A stall is *defined* by
+  the tree not moving, so the two rungs that exist for exactly this situation could never fire in
+  it. That guard is a review-bounce policy — do not bounce REVIEW backwards again if nothing changed
+  — and it stays that for review bounces; the stuck ladder opts out explicitly.
+- **The budgets counted effects on disk**, which only appear if the agent acts on the advice. A
+  stuck agent does not, so the budget never moved and the ladder jammed, offering `replan` forever.
+  Each rung now gets one turn per stall; the on-disk budgets still bound the run across stalls.
+- **MASTER defaulted to a specific third-party model** — in a package whose 2.0.0 release promised
+  every routing slot ships empty. The last rung of the ladder silently redirected the hardest work
+  in the run to one vendor. It is `null` now, meaning "whatever pi is configured with", unless the
+  user chose one.
+
+### Changed
+
+- A stalled iteration consults the ladder before the no-progress strike is spent, and a new rung
+  resets the streak — a different attempt is not another repetition of the same one. This cannot run
+  forever: every rung is bounded, so the ladder runs out, returns nothing, and the run stops with a
+  full account of what was tried.
+- `loop-state.json` carries the ladder's position. State written before it existed loads fine.
+
+---
+
+## [2.1.0] — 2026-08-23
+
+You could not start, and if you had, you could not have got past the first gate. Both are fixed.
+
+### Added
+
+- **`/infinity:init`, and the `infinity_init` tool.** There was no way to create a harness. `pi
+  install` put the extension in place and then every command answered *"No harness in this project
+  (harness/config.json not found)"* — with nothing anywhere that made one. The package installed,
+  loaded, and passed its entire test suite while being unusable.
+
+  Init detects the stack and its lint/test/build commands, writes the config, an empty plan, the
+  phase and role docs the brief points at, and starters for the documents the review gate demands,
+  then hands the model its first brief. It asks two questions when there are dialogs and takes the
+  detected defaults when there are not, so an unattended run never stalls on a prompt. It never
+  overwrites an existing file, and `/infinity:init force` restores what was deleted without touching
+  what was written.
+- **Feature names, acceptance criteria and the run's goal are writable through `infinity_plan`.**
+  Features are derived from task keys, so there was no input for their metadata — and the DEFINE
+  gate requires criteria on every feature. The first gate in the pipeline could only be passed by
+  hand-editing the plan file, which the brief explicitly tells you not to do.
+
+  `features` merges by id and never deletes, because features are inferred rather than submitted;
+  `tasks` keeps its omission-means-deletion rule. Leaving `tasks` out entirely is now distinct from
+  sending `[]`: absent means "not touching them", empty still means "delete them all". Nesting tasks
+  inside a feature — the obvious wrong guess — is refused with the shape that works.
+- **A `coldstart` E2E scenario**: bare directory, `/infinity:init`, brief, plan, gate, advance,
+  through the real adapter. Every leg of it was a defect before it was a test.
+
+### Fixed
+
+- **Six more shipped documents told the agent to run a CLI this package does not have** —
+  `infinity-harness contract propose`, `decision "..."`, `rollback list`, `checkpoint create`. The
+  2.0.2 guard only caught a hardcoded list of verbs, which by construction only ever catches the
+  ones already found. It now looks at *where* the claim is made: inside a code fence or span, the
+  package name followed by a word is a command line, and there is no command line.
+- **The plan view hid the thing the model is marked on.** Reading the plan listed tasks but not
+  features or their criteria — so the DEFINE gate judged something the model could not see. It now
+  shows the goal, each feature, and its criteria, flagging any feature that has none.
+- **Comments counted as document content.** `docCheck` stripped headings but not HTML comments, so a
+  scaffolded file whose guidance lived in a comment would satisfy the gate that demanded it. A
+  comment is instructions to the author, not content.
+
+---
+
 ## [2.0.4] — 2026-08-23
 
 ### Changed

package/README.md

@@ -77,20 +77,55 @@ cd your-project
 pi
 ```
 
-On session start the harness injects a brief — phase, role, current task, acceptance criteria, and
-what to do next. Do the work, then:
+Then, once, in that project:
+
+```
+/infinity:init
+```
+
+That is the whole setup. It detects your stack and its lint/test/build commands, writes
+`harness/` with the config, an empty plan, the phase and role docs, and starters for the
+documents the review gate will demand — then hands the model its first brief. It never
+overwrites a file that already exists, and `/infinity:init force` restores anything you
+deleted without touching what you wrote.
+
+From then on, every session opens with a brief: phase, role, current task, acceptance criteria,
+the craft skills that match the work, and what to do next. Do the work, then:
 
 ```
 /infinity:validate     run the gate for this phase
 /infinity:run          hand it the wheel: validate → advance → re-brief, until done or stuck
+/infinity:status       where the run is right now
 /infinity:config       change any setting, including which model runs which tier
 /infinity:models       what models pi has, and how they are being routed
 /infinity:dashboard    open the live web view
+/infinity:goal         state a goal and pursue it across passes
+/infinity:unstuck      what the escalation ladder would try next
+/infinity:rework       send a task and its dependents backwards
 /infinity:halt         take the wheel back
 ```
 
 `/infinity:run` is the point of the tool. It keeps the loop turning without you.
 
+### The first pass through
+
+DEFINE wants acceptance criteria on every feature, so start by telling it what you are building.
+The agent writes that through `infinity_plan`:
+
+```jsonc
+{
+  "goal": "Ship the payments rewrite behind a flag",
+  "features": [
+    { "id": "feature-001", "name": "Checkout flow", "criteria": ["refunds reconcile against the ledger"] }
+  ]
+}
+```
+
+Features carry names and criteria; tasks are a separate list keyed `feature-001/task-001`, and
+arrive in PLAN. Omitting a task deletes it — that is the rule that keeps the plan honest — but
+omitting a *feature* just leaves it alone, because features are inferred from task keys rather
+than submitted.
+
 ## Configuration
 
 Everything is configurable from inside pi:
@@ -132,6 +167,49 @@ define → plan → build → verify → [simplify] → review → ship
 
 Enable or disable phases in `harness/config.json` under `phases.enabled`. SIMPLIFY is off by default.
 
+## When it gets stuck
+
+Stopping safely is the easy half. The hard half is trying something *else* first, and that is the
+escalation ladder: when a run stalls — the gate fails and the working tree has not moved, meaning
+the agent produced nothing — `/infinity:run` climbs it before spending a strike.
+
+| Rung | What it does |
+|---|---|
+| **retry** | One more attempt. Sometimes a run is just slow. |
+| **reframe** | State the assumption you have been working under, say why the evidence contradicts it, then try a different approach. |
+| **consult** | Escalate to a stronger model, one step up the difficulty ladder. |
+| **rework** | Flip the task and everything that depends on it back to `rework`. Work built on a broken thing is suspect until re-proved. |
+| **replan** | The plan is wrong: something this needed was never planned. Amend it. |
+| **master** | Last resort. State the problem from scratch, including what has been ruled out. |
+
+Each rung gets one turn per stall, and each is bounded — reworks and replans have budgets, `consult`
+has a per-task limit, `master` fires once per run. When the ladder runs out, the run stops and names
+every rung it spent. Real progress resets it: a moving tree means a new problem, and a new problem
+gets a fresh ladder.
+
+`/infinity:unstuck` shows what it would try next without doing it.
+
+## Goals, and knowing when you are actually done
+
+A finished pipeline is not a met goal. The gate decides whether the **work** is done; it has no
+opinion on whether the work was the *right* work, because it only ever sees the plan — and the plan
+is just what you thought the goal needed when you wrote it.
+
+```
+/infinity:goal Ship the payments rewrite behind a flag
+```
+
+That states the goal and starts pass 1. One pass at the goal is one full trip through the pipeline.
+When the pipeline completes, the run does not end: it asks whether the goal is met.
+
+- **complete** ends the run.
+- Anything else must name what is still missing — and the pipeline rewinds to the first phase with
+  that list carried into the brief, so the next pass plans for the remainder rather than rebuilding
+  what the last review already accepted.
+
+Bounded by an iteration ceiling and a wall clock, both configurable. The widget shows which pass you
+are on, because a second pass looks exactly like a first one otherwise.
+
 ## Knowing when to stop
 
 This is the part that makes an unattended run safe. `/infinity:run` halts on any of:
@@ -166,7 +244,12 @@ brief all read it; nothing caches a second copy.
 
 The agent edits it by submitting the **complete** task list through the `infinity_plan` tool:
 
-- **Omission means deletion.** One unambiguous rule beats incremental edits a model loses track of.
+- **Omission means deletion** — for tasks. One unambiguous rule beats incremental edits a model
+  loses track of. Leaving the `tasks` field out entirely is different from sending an empty one:
+  absent means "not touching them", empty means "delete them all".
+- **Features are a merge, not a submission.** They are inferred from task keys, so they are never
+  resubmitted wholesale; `features` supplies names and acceptance criteria by id, and omitting one
+  leaves it alone.
 - **`baseRevision` guards every write.** A stale revision is rejected, so parallel workers can't
   clobber each other.
 - **Unknown fields survive.** An update merges onto the stored task, so `difficulty`, `modelHint`,
@@ -241,11 +324,17 @@ that looks like a broken endpoint but is only a small cap.
 
 | Tool | Purpose |
 |---|---|
+| `infinity_init` | Create the harness in this project |
 | `infinity_brief` | What am I supposed to be doing right now? |
-| `infinity_plan` | Read or rewrite the task list |
+| `infinity_plan` | Read or rewrite the plan — tasks, features, criteria, goal |
 | `infinity_validate` | Run the gate for this phase |
 | `infinity_advance` | Move to the next phase (refuses on a failing gate) |
 | `infinity_dashboard` | Start/stop/query the web view |
+| `infinity_unstuck` | What should I try next? (recommends; does not act) |
+| `infinity_rework` | Send a task and its dependents back to rework |
+| `infinity_replan` | Add what the plan was missing, mid-run |
+| `infinity_spawn_worker` | Attempt one task in a clean-room worker |
+| `infinity_goal` | State a goal, review it, or check which pass it is on |
 
 ## Layout
 
@@ -258,19 +347,21 @@ infinity-harness/
 │   │                              · skills (match) · skillsAudit (guard)
 │   ├── ui/                        theme · widget (terminal) · dashboard (web)
 │   ├── loop.ts                    the continuous-run driver and its stop conditions
+│   ├── escalate.ts                the ladder's actuator: chooses a rung and takes it
+│   ├── goal.ts                    the outer loop: is the thing asked for actually done?
 │   ├── taskList.ts                atomic plan editor
 │   ├── worker.ts                  isolated per-task workers
 │   ├── modelRouter.ts             difficulty ladder + consultation
 │   ├── rework.ts · replan.ts      backward rework with BFS impact · mid-build amendment
 │   ├── unstuck.ts · review.ts     escalation strategy matrix · review bounce guard
-│   └── goalLoop.ts · goalState.ts · goalSpec.ts
+│   └── goalLoop.ts · goalState.ts · goalSpec.ts   goal state machine and its store
 ├── harness/
 │   ├── features/feature-list.json the plan
 │   ├── config.json                pipeline state and settings
 │   ├── model-router.json          optional routing
 │   ├── docs/                      architecture · decisions · phase and role docs
 │   └── skills/                    28 craft skills the brief points at
-├── tests/                         23 files, plain node:assert
+├── tests/                         28 files, plain node:assert
 └── scripts/run-tests.mjs
 ```
 
@@ -282,7 +373,7 @@ there is one implementation, and the adapter calls it.
 ```bash
 npm install
 npm run check    # tsc --noEmit
-npm test         # 23 test files
+npm test         # 28 test files
 npm run e2e      # end-to-end against a live model
 ```