infinity-harness 2.0.0

package/harness/docs/ARCHITECTURE.md

@@ -0,0 +1,159 @@
+# Architecture
+
+infinity-harness is a pi extension that drives an agent through a gated build pipeline and keeps it
+going, unattended, for hours or days.
+
+The whole design rests on one idea: **take two decisions away from the model.** When work is done is
+decided by a deterministic gate, not the agent's judgement. What happens next is decided by a
+forward-only phase machine, not the agent's preference. Everything else exists to keep those two
+decisions honest across a very long run.
+
+## Shape
+
+```
+                        ┌──────────────────────────────────┐
+   pi lifecycle ──────► │ extensions/infinity-harness      │   thin adapter
+                        │ hooks · tools · commands         │   no logic of its own
+                        └───────────────┬──────────────────┘
+                                        │
+        ┌───────────────────────────────┼───────────────────────────────┐
+        ▼                               ▼                               ▼
+   ┌─────────┐                   ┌─────────────┐                 ┌───────────┐
+   │ loop.ts │                   │  taskList   │                 │    ui/    │
+   │ decide  │                   │  atomic     │                 │ widget    │
+   │ next    │                   │  plan edit  │                 │ dashboard │
+   └────┬────┘                   └──────┬──────┘                 └─────┬─────┘
+        │                               │                              │
+        └───────────────┬───────────────┴──────────────────────────────┘
+                        ▼
+              ┌───────────────────────────────────────────────┐
+              │ src/core/                                     │
+              │ types · paths · fsx · lock · exec             │
+              │ config · phases · gates · brief · featureList  │
+              └───────────────────────┬───────────────────────┘
+                                      ▼
+                            harness/  (state on disk)
+                            config.json · features/feature-list.json
+```
+
+**The extension is thin on purpose.** An earlier version inlined its own copies of the plan engine
+and the widget, so the tested code and the shipped code were two different implementations that
+drifted apart. There is one implementation now, in `src/`, and the adapter calls it. The same rule
+applies to every module: if you find yourself writing a private `loadFeatureList`, stop — that
+mistake has already been made twice and fixed twice.
+
+## Layers
+
+### `src/core/` — owned foundations
+
+| Module | Responsibility |
+|---|---|
+| `types.ts` | Every shape crossing a module boundary. No I/O; safe to import anywhere. |
+| `paths.ts` | The only place a `harness/…` path is spelled out. |
+| `fsx.ts` | Atomic JSON writes, `.bak` snapshots, absent-vs-corrupt reads. |
+| `exec.ts` | Every shell-out, bounded by a timeout. Never throws; failures are data. |
+| `lock.ts` | `withLockSync` (exclusive, fail-closed) and `withLock` (advisory, best-effort). |
+| `config.ts` | `harness/config.json` — pipeline state, retry budgets, gate history. |
+| `phases.ts` | The forward-only state machine and `transitionPhase`. |
+| `gates.ts` | The deterministic checks and the runner. |
+| `featureList.ts` | The plan on disk: load, save, flatten, progress, dependency integrity. |
+| `brief.ts` | "What do I do now?", assembled from state and rendered for a model. |
+
+These were ported to TypeScript from a sibling CLI project that used to be reached through a symlink.
+The symlink made the package unshippable — it pointed at an absolute path on one developer's
+machine — so the needed logic is now owned, typed, and tested here.
+
+### `src/` — the harness proper
+
+- **`taskList.ts`** — the atomic plan editor. The agent submits the complete list; omission means
+  deletion; `baseRevision` guards the write; unknown fields survive.
+- **`loop.ts`** — `decideNext()`: given state on disk, continue, advance, wait, or stop.
+- **`worker.ts`** — isolated per-task workers under `tmp/infinity-harness/<run>/`.
+- **`modelRouter.ts`** — optional difficulty ladder, disabled and vendor-neutral by default.
+- **`rework.ts` / `replan.ts`** — bounded backward movement: BFS impact analysis, DAG-guarded
+  mid-build amendment.
+- **`unstuck.ts` / `review.ts`** — escalation strategy matrix; the REVIEW bounce guard.
+- **`remote.ts`** — the read-only dashboard server.
+
+### `src/ui/` — the visible surface
+
+- **`theme.ts`** — ANSI-aware width, wrapping, truncation, colour degradation, glyph fallback.
+- **`widget.ts`** — the terminal plan view.
+- **`dashboard.ts`** — the web plan view, same information design.
+
+## Data flow
+
+```
+session_start ──► buildBrief ──► renderBrief ──► sendMessage        the agent is told what to do
+                     ▲
+                     │
+agent works ─────────┼──► infinity_plan ──► writeTaskList ──► feature-list.json
+                     │                          (locked)              │
+                     │                                                ▼
+agent_settled ──► decideNext ──► runChecks ──► gate verdict      widget · dashboard
+                     │                │
+                     │                ├── pass ──► advancePhase ──► new brief ──► next turn
+                     │                └── fail ──► re-brief with the failing checks
+                     │
+                     └── budgets exhausted / no progress / paused ──► stop, with a reason
+```
+
+Nothing caches a second copy of the plan. The widget, the dashboard and the brief all read
+`feature-list.json`, so the visible state is always the real state — even when the agent's own
+narration has drifted.
+
+## Concurrency
+
+Parallel workers write the same plan file. `baseRevision` detects a stale **read**; it cannot
+serialise a read-modify-write. Two processes that both read revision N both pass the check and both
+write N+1, and one set of edits is gone — measured at 2 lost updates in a 6-way fan-out.
+
+So `writeTaskList` holds an exclusive lock across the entire read-apply-write, and **fails closed**:
+if the lock cannot be taken, the write is refused with an error the caller can retry, rather than
+racing and losing an edit silently.
+
+Two details that cost real debugging time:
+
+- The sync lock uses `<path>.ilock`, **not** `<path>.lock` — the latter is what `proper-lockfile`
+  uses, and it is a directory there too. Sharing the name made a nested async+sync lock deadlock
+  against itself.
+- Locks are held for the duration of the *work*, never across an agent turn. An earlier version took
+  a lock at the start of a turn with an 8-second staleness timeout, so every turn longer than eight
+  seconds left a lock another process was entitled to steal.
+
+## Stopping
+
+Continuing is easy; knowing when to stop is the hard part, and the difference between a useful
+overnight run and a wasted weekend of tokens.
+
+| Guard | Catches |
+|---|---|
+| No-progress detector | The gate keeps failing and the tree fingerprint hasn't moved — spinning, not working |
+| Wall clock | A run nobody remembered to stop |
+| Iteration ceiling | Runaway loops that stay under the clock |
+| Retry budgets | One impossible task consuming the run |
+| Human brake | `paused`, `/infinity:halt`, or `harness/STOP` |
+
+The fingerprint is `git status --porcelain` + HEAD + the plan revision and task statuses. The first
+failing iteration establishes a baseline and never counts as a stall — there is nothing to compare
+against yet.
+
+Every stop carries a reason. A human coming back finds an explanation, not a mystery.
+
+## Failure posture
+
+- **Reads distinguish absent from corrupt.** A missing plan seeds an empty one; a corrupt plan
+  recovers the previous good revision from `.bak` rather than silently starting over.
+- **Advisory checks never fail a gate.** A gate that fails for a reason the agent cannot fix
+  deadlocks the loop, so an unconfigured lint command is reported, not enforced.
+- **Errors are data where the caller can continue** (`{ ok, error }`), thrown where it cannot.
+- **The dashboard cannot perturb the run.** Read-only, loopback-only, and it never runs the gate —
+  running lint and tests because someone opened a web page would be a surprising side effect.
+
+## 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
+  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/CONSTRAINTS.md

@@ -0,0 +1,19 @@
+# Constraints
+
+## Technical
+
+- **Language:** node
+- **Platform:** <!-- target platform -->
+- **Dependencies:** <!-- key dependency constraints -->
+
+## Process
+
+- Commits must be atomic (one concern per commit)
+- All code reviewed before merging
+- Tests must pass before shipping
+
+## Design
+
+- Favor simplicity over generality
+- Explicit over implicit
+- Fail fast, fail loud

package/harness/docs/DECISIONS.md

@@ -0,0 +1,107 @@
+# Decisions
+
+Architectural decisions and the reasoning behind them. Outcomes without reasons are useless to the
+next person — record why, and what it cost.
+
+---
+
+## 1. The gate is the only referee
+
+**Context.** An agent asked whether its work is finished will say yes. Repeatedly, and wrongly, over
+a long run.
+
+**Decision.** Completion is decided by deterministic checks that are a pure function of the project
+on disk. The agent cannot mark its own work complete, and the extension blocks hand-edits to
+`currentPhase` while the gate is failing.
+
+**Cost.** Gates must be cheap enough to run every iteration, and must never fail for a reason the
+agent cannot fix — a gate that deadlocks the loop is worse than no gate. Hence advisory checks:
+an unconfigured lint command is reported, not enforced.
+
+---
+
+## 2. Phases move forward, one step at a time
+
+**Decision.** `isValidTransition` permits only the next enabled phase, or re-running the current one.
+Backward movement exists only as an explicit, budgeted rework that records why it happened.
+
+**Why.** It removes a decision the model is bad at. Without it, a struggling agent reorders the
+pipeline to reach a phase whose gate it can pass.
+
+---
+
+## 3. The plan is submitted whole; omission means deletion
+
+**Decision.** `infinity_plan` takes the complete task list, not a patch.
+
+**Why.** Incremental edits require the model to track what exists. Over hours it stops being able to:
+it re-adds deleted tasks, forgets others, and the file diverges from reality. A full submission is
+self-correcting, and one unambiguous rule beats a set of merge semantics nobody can predict.
+
+**Cost.** Every write carries the whole plan. Capped at 200 tasks, which is far beyond a sensible
+sprint.
+
+---
+
+## 4. `baseRevision` is not a compare-and-swap
+
+**Context.** The original write did read → check `baseRevision` → write, with no mutual exclusion,
+and the docs claimed this protected parallel workers. It does not. Two processes that both read
+revision N both pass the check and both write N+1. Measured: 2 lost updates in a 6-way fan-out.
+
+**Decision.** `writeTaskList` holds an exclusive lock across the whole read-apply-write and fails
+closed — a write that cannot take the lock is refused, not raced.
+
+**Cost.** Plan writes serialise. The critical section is milliseconds, so this is not felt; a
+`LockTimeoutError` is retryable and names the stuck lock.
+
+**Also.** The sync lock uses `<path>.ilock`. `proper-lockfile` owns `<path>.lock` and it is a
+directory there too, so sharing the name made a nested async+sync lock deadlock against itself.
+
+---
+
+## 5. One implementation, in `src/`
+
+**Context.** The extension carried inlined copies of the plan engine and the widget. The tests
+exercised `src/`; the shipped code path never called it. The two drifted, and the drift was
+invisible because the suite was green. The same pattern later reappeared in `rework.ts` and
+`replan.ts`, which kept private plan loaders — and one of them mishandled status aliases, rejecting
+every amendment to a plan that used `"done"`.
+
+**Decision.** `src/` is the single implementation. The extension owns pi's lifecycle and nothing
+else. A private `loadFeatureList` is a bug, not a shortcut.
+
+---
+
+## 6. Knowing when to stop is the product
+
+**Decision.** The loop halts on no-progress, wall clock, iteration count, retry budgets, or a human
+brake — and every stop names its reason.
+
+**Why.** Continuing is trivial. The default failure mode of an autonomous loop with a weak model is
+re-running a failing gate against an unchanged tree until the budget is gone. The no-progress
+detector compares a fingerprint of the working tree and the plan; the first failing iteration is a
+baseline and never counts as a stall.
+
+---
+
+## 7. Ship vendor-neutral defaults
+
+**Context.** The router shipped enabled, with one third-party vendor's model ids hardcoded in every
+slot.
+
+**Decision.** Routing is disabled by default and every slot is empty, meaning "use whatever model pi
+is already configured with". Installing an extension must never silently redirect someone's work to
+a model they did not choose.
+
+---
+
+## 8. The dashboard cannot perturb the run
+
+**Decision.** Read-only, loopback-only, and it does not run the gate — it reports the last recorded
+verdict instead.
+
+**Why.** Running lint and the test suite because someone opened a web page is a surprising and
+expensive side effect. And a page rendering model output on a public interface leaks the project;
+binding elsewhere requires an explicit opt-in, and the CSP is tight enough that an escaping slip
+cannot become script execution.

package/harness/docs/DOMAIN.md

@@ -0,0 +1,13 @@
+# Domain Glossary
+
+<!-- The project's ubiquitous language. One concept, one name — everywhere:
+     spec, code, tests, docs. Add terms the moment they're resolved (see
+     harness/skills/domain-modeling.md). Glossary ONLY — no implementation
+     details, no scratch notes. -->
+
+## Terms
+
+### ExampleTerm
+<!-- Definition. What it IS, what it is NOT, and which nearby concept it
+     must not be confused with. Delete this example when adding the first
+     real term. -->

package/harness/docs/agents/evaluator.md

@@ -0,0 +1,14 @@
+# Evaluator Role
+
+Tone: Skeptical and thorough. Accept only compelling evidence.
+
+You verify. You gate. You are the final authority.
+
+- Do NOT trust "seems right" — require proof
+- Run the verification commands yourself
+- If criteria are ambiguous, reject with specific reason
+- "Pass" means all checks pass; "Fail" means at least one check is insufficient
+- In DEFINE: review sprint-contract.md for clarity and testability
+- In REVIEW: check all phase gates, branch alignment, changelog
+- Use `evaluator-rubric.md` to score quality across 6 dimensions
+- Gate failures escalate to human after max retries

package/harness/docs/agents/generator.md

@@ -0,0 +1,13 @@
+# Generator Role
+
+Tone: Focused and practical. Build what's specified.
+
+You implement. You produce artifacts. You self-check.
+
+- Build exactly what the Planner specified
+- Do not add scope or "future-proof"
+- Run lint + tests before handoff
+- 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`

package/harness/docs/agents/planner.md

@@ -0,0 +1,13 @@
+# Planner Role
+
+Tone: Analytical and precise. Define clear boundaries.
+
+You design the approach. You write criteria. You set scope.
+
+- Propose what to build in sprint-contract.md
+- Define unambiguous acceptance criteria
+- Set exclusions explicitly ("We will NOT build X")
+- Hand off to Generator when criteria are clear
+- In DEFINE: interview the user, write PRD in specs/*.md
+- In PLAN: decompose features into tasks in harness/features/feature-list.json
+- Review gate criteria with Evaluator before proceeding

package/harness/docs/agents/simplifier.md

@@ -0,0 +1,13 @@
+# Simplifier (Generator Persona for SIMPLIFY Phase)
+
+Tone: Relentless about clarity. Delete more than you add.
+
+You refactor. You clean. You never change behavior.
+
+- Flatten nesting — max 4 levels
+- Remove dead code and commented-out blocks
+- Extract repeated logic into shared functions
+- 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

package/harness/docs/api-patterns.md

@@ -0,0 +1,23 @@
+# API Patterns
+
+## Conventions
+
+<!-- Document API conventions: URL structure, auth, error format, pagination -->
+
+## Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | /api/v1/... | ... |
+| POST | /api/v1/... | ... |
+
+## Error Format
+
+```json
+{
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "Human-readable description"
+  }
+}
+```

package/harness/docs/phases/build.md

@@ -0,0 +1,47 @@
+# BUILD Phase
+
+## Overview
+Implement each feature task-by-task. The task loop iterates features and tasks,
+producing instructions for each. Validate after each task before advancing.
+
+## When to Use
+- PLAN phase complete (feature list + sprint contract exist)
+- Ready to write code
+
+## Craft Skills (read before working)
+- `harness/skills/tdd.md` — red → green loop; what makes a test worth keeping
+- `harness/skills/prototype.md` — when a design question can't be answered on paper
+- `harness/skills/diagnosing-bugs.md` — when something breaks mid-build
+
+## 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)
+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
+   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
+
+## Rationalizations to Avoid
+| Excuse | Rebuttal |
+|--------|----------|
+| "I'll validate at the end" | Late validation catches problems when they're expensive to fix |
+| "This task is trivial, skip validation" | Trivial tasks still have edge cases |
+| "The tests pass, so it works" | Tests must cover acceptance criteria, not just happy path |
+
+## Red Flags
+- Tasks marked complete without validation
+- Features with all tasks complete but `passes: false` — run validate
+- Tests that only test the implementation, not the behavior
+
+## Verification
+- [ ] Each task validated with `the infinity_validate tool --feature X --task Y`
+- [ ] All features marked `passes: true` in feature-list.json
+- [ ] `the infinity_validate tool` passes (full phase gates)
+
+## Handoff
+On gate pass: `the infinity_advance tool` (Generator → Evaluator for VERIFY)

package/harness/docs/phases/define.md

@@ -0,0 +1,58 @@
+# DEFINE Phase
+
+## Overview
+Interview the user, capture intent, and write a bounded PRD. The output is a
+short, unambiguous specification that the PLAN phase can decompose into a
+feature list.
+
+## When to Use
+- Pipeline is at DEFINE phase (first phase after INIT)
+- No `specs/prd.md` exists yet
+- User needs to define what to build before planning how
+
+## Craft Skills (read before working)
+- `harness/skills/grilling.md` — stress-test the spec with relentless questions before committing to it
+- `harness/skills/domain-modeling.md` — pin down domain terms in `harness/docs/DOMAIN.md`
+- `harness/skills/research.md` — answer blocking factual questions from primary sources
+
+## Process
+1. Read `harness/progress.md` and `AGENTS.md` for context
+2. Interview the user to surface objectives, constraints, and exclusions
+   (follow `harness/skills/grilling.md`; in autopilot, self-grill and record
+   the Q&A in the PRD)
+3. **If stack is custom/unknown**, fill `stackMeta` in `harness/config.json`:
+   - `testCmd`, `lintCmd`, `buildCmd`, `installCmd`, `coverageCmd`, `configFile`, `extensions`
+4. **Define project folder structure** — agree on directory layout:
+   - `src/` for source, `tests/` for tests, `docs/` for docs, `scripts/` for automation
+   - No source files in project root
+5. Write `specs/prd.md` — scope, success criteria, non-goals
+6. Keep the PRD bounded: no vague verbs ("improve", "enhance")
+7. **Negotiate the sprint contract** (the DEFINE gate requires it agreed):
+   - `infinity-harness contract propose --scope "..." --criteria "tests pass|feature X works"`
+   - `infinity-harness contract review --agreed` (put on the evaluator hat: would
+     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
+
+## Rationalizations to Avoid
+| Excuse | Rebuttal |
+|--------|----------|
+| "The spec is obvious, let's just build" | Without a PRD, scope creeps and features drift |
+| "I'll define it as I go" | Ambiguity compounds — define boundaries upfront |
+
+## Red Flags
+- PRD longer than 2 pages — scope is too broad
+- Vague success criteria ("works well", "fast enough")
+- No non-goals section — everything is in scope
+
+## Verification
+- [ ] `specs/prd.md` exists with scope, success criteria, non-goals
+- [ ] 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
+
+## Handoff
+On gate pass: `the infinity_advance tool` (Planner → continues as Planner for PLAN)

package/harness/docs/phases/plan.md

@@ -0,0 +1,50 @@
+# PLAN Phase
+
+## Overview
+Decompose the PRD into a feature list with bounded tasks. Each feature becomes
+a unit of work that BUILD can implement and VERIFY can validate independently.
+
+## When to Use
+- DEFINE phase complete (PRD exists)
+- Need to break PRD into implementable features and tasks
+
+## Craft Skills (read before working)
+- `harness/skills/planning-tasks.md` — tracer-bullet vertical slices + the feature-list format
+- `harness/skills/codebase-design.md` — shape features around deep modules with small interfaces
+
+## Process
+1. Read `harness/progress.md`, `AGENTS.md`, and `specs/prd.md`
+2. Decompose the PRD into features — each a **vertical slice** that is
+   demoable on its own (see `harness/skills/planning-tasks.md`)
+3. For each feature, define tasks — each a single, testable change sized to
+   one working session
+4. Write `harness/features/feature-list.json`. Every task needs
+   `acceptanceCriteria` (1–3 concrete, checkable statements); every feature
+   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
+
+> The sprint contract was agreed in DEFINE. If PLAN reveals the scope was
+> wrong, renegotiate it now (`contract propose` → `contract review`) — not
+> silently during BUILD.
+
+## Rationalizations to Avoid
+| Excuse | Rebuttal |
+|--------|----------|
+| "Tasks are obvious from the PRD" | Undecomposed tasks lead to incomplete implementations |
+| "I'll plan during build" | Context switching kills momentum — plan first |
+
+## Red Flags
+- Features with more than 7 tasks — too coarse, decompose further
+- Tasks with vague descriptions ("handle edge cases") — specify what
+- No sprint contract — no agreement on scope
+
+## Verification
+- [ ] `feature-list.json` exists with features and tasks
+- [ ] Sprint contract proposed and agreed
+- [ ] `the infinity_validate tool` passes
+
+## Handoff
+On gate pass: `the infinity_advance tool` (Planner → Generator for BUILD)

package/harness/docs/phases/review.md

@@ -0,0 +1,47 @@
+# REVIEW Phase
+
+## Overview
+Final quality gate before shipping. The Evaluator reviews the complete codebase
+against the evaluator rubric, checks documentation, and ensures the branch is
+up-to-date with upstream.
+
+## When to Use
+- BUILD/VERIFY/SIMPLIFY phases complete
+- Ready for final quality review before release
+
+## Craft Skills (read before working)
+- `harness/skills/code-review.md` — two-axis review: spec fidelity + standards/smells
+
+## Process
+1. Read `harness/progress.md`, `AGENTS.md`, and `harness/evaluator-rubric.md`
+2. Run `the infinity_status command` 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.
+4. Review codebase against evaluator rubric (6 dimensions, 0-2 each):
+   - 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
+
+## Rationalizations to Avoid
+| Excuse | Rebuttal |
+|--------|----------|
+| "Build and verify already checked quality" | Review is holistic — catches cross-cutting issues |
+| "Documentation can be added post-ship" | Docs shipped late are docs shipped never |
+| "The rubric is too strict" | The rubric encodes minimum quality — meet it |
+
+## Red Flags
+- Rubric score below 8/12 — quality is marginal
+- Missing README, CHANGELOG, or architecture docs
+- Branch behind upstream — merge before shipping
+
+## Verification
+- [ ] Evaluator rubric score >= 8/12
+- [ ] README.md, CHANGELOG.md exist and are current
+- [ ] Branch up-to-date with upstream
+- [ ] `the infinity_validate tool` passes
+
+## Handoff
+On gate pass: `the infinity_advance tool` (Evaluator → Generator for SHIP)

package/harness/docs/phases/ship.md

@@ -0,0 +1,43 @@
+# SHIP Phase
+
+## Overview
+Prepare and execute the release. Tag the version, finalize changelog, verify
+clean working tree, and ensure all ship gates pass.
+
+## When to Use
+- REVIEW phase complete
+- Ready to release
+
+## Process
+1. Read `harness/progress.md` and `AGENTS.md`
+2. Run `the infinity_status command` 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!)
+9. Create checkpoint: `infinity-harness checkpoint create release-<version>`
+
+## Rationalizations to Avoid
+| Excuse | Rebuttal |
+|--------|----------|
+| "I'll tag after deploying" | Tag before deploying — you want a known-good rollback point |
+| "CHANGELOG can wait" | Users need to know what changed — write it now |
+| "Working tree has minor changes" | Ship from clean tree only — commit or stash first |
+
+## Red Flags
+- Uncommitted changes in working tree
+- No version tag created
+- CHANGELOG.md missing or empty
+- LICENSE or CONTRIBUTING.md missing
+
+## Verification
+- [ ] Working tree clean: `git status` shows no changes
+- [ ] Version tag created: `git tag -l "v*"`
+- [ ] CHANGELOG.md updated with version + changes
+- [ ] README.md, LICENSE, CONTRIBUTING.md exist
+- [ ] `the infinity_validate tool` passes
+
+## Handoff
+On gate pass: Pipeline complete! `the infinity_status command` shows "Pipeline complete".