infinity-harness 2.0.4 → 2.1.0

package/CHANGELOG.md

@@ -4,6 +4,51 @@ 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.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,12 +77,25 @@ 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
@@ -91,6 +104,25 @@ what to do next. Do the work, then:
 
 `/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:
@@ -166,7 +198,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,8 +278,9 @@ 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 |
@@ -270,7 +308,7 @@ infinity-harness/
 │   ├── 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/                         25 files, plain node:assert
 └── scripts/run-tests.mjs
 ```
 
@@ -282,7 +320,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         # 25 test files
 npm run e2e      # end-to-end against a live model
 ```
 

package/extensions/infinity-harness/index.ts

@@ -26,13 +26,19 @@ import { runChecks } from "../../src/core/gates.ts";
 import { advancePhase } from "../../src/core/phases.ts";
 import { configPath } from "../../src/core/paths.ts";
 import { withLock } from "../../src/core/lock.ts";
-import { ValidationError, type FeatureList, type Phase } from "../../src/core/types.ts";
+import {
+  DEFAULT_ENABLED_PHASES,
+  ValidationError,
+  type FeatureList,
+  type Phase,
+} from "../../src/core/types.ts";
 import { writeTaskList, summarizeApply, type TaskInput } from "../../src/taskList.ts";
 import { renderWidget, renderStatusLine, type WidgetState } from "../../src/ui/widget.ts";
 import { createStyler, detectGlyphs } from "../../src/ui/theme.ts";
 import { decideNext, stopFilePath } from "../../src/loop.ts";
 import { runConfigMenu, renderSettings, type ModelChoice, type Prompter } from "../../src/ui/config.ts";
 import { SETTINGS, readAll, readSetting, formatValue } from "../../src/core/settings.ts";
+import { detectStack, describeInit, initHarness, type StackId } from "../../src/core/init.ts";
 
 const CHECKPOINT = "infinity:checkpoint";
 const WIDGET_KEY = "infinity-harness";
@@ -438,22 +444,72 @@ export default function (pi: ExtensionAPI): void {
             },
           },
         },
+        features: {
+          type: "array",
+          maxItems: 100,
+          description:
+            "Feature names and acceptance criteria, merged by id. Unlike tasks, omitting a feature " +
+            "here leaves it alone rather than deleting it. The DEFINE gate requires criteria on " +
+            "every feature, so this is how DEFINE is passed.",
+          items: {
+            type: "object",
+            required: ["id"],
+            properties: {
+              id: { type: "string", description: 'Feature id, e.g. "feature-001"' },
+              name: { type: "string", description: "What the feature is, in a few words" },
+              description: { type: "string" },
+              criteria: {
+                type: "array",
+                items: { type: "string" },
+                description: "How you will know this feature is done. Observable, not aspirational.",
+              },
+            },
+          },
+        },
+        goal: {
+          type: "string",
+          description: "One line: what this whole run is for. Shown at the top of every brief.",
+        },
       },
     } as never,
-    async execute(_id: string, params: { baseRevision?: number; tasks?: TaskInput[] }, _signal, _onUpdate, ctx) {
+    async execute(
+      _id: string,
+      params: {
+        baseRevision?: number;
+        tasks?: TaskInput[];
+        features?: { id: string; name?: string; description?: string; criteria?: string[] }[];
+        goal?: string;
+      },
+      _signal,
+      _onUpdate,
+      ctx,
+    ) {
       const dir = projectDir(ctx);
 
-      if (!Array.isArray(params?.tasks)) {
+      // A submission with no tasks, no features and no goal is a read.
+      const writing =
+        Array.isArray(params?.tasks) || Array.isArray(params?.features) || typeof params?.goal === "string";
+      if (!writing) {
         const { list } = loadFeatureList(dir);
         const p = computeProgress(list);
+        // Features and their criteria are printed, not just tasks: the DEFINE
+        // gate judges criteria, so a plan view that hides them shows the model
+        // everything except the thing it is being marked on.
         const rows = (list.features ?? [])
-          .flatMap((f) => (f.tasks ?? []).map((t) => `[${t.status}] ${t.key ?? t.id}: ${t.description}`))
+          .flatMap((f) => [
+            `${f.id} · ${f.name}${f.criteria?.length ? "" : "  ← no acceptance criteria"}`,
+            ...(f.criteria ?? []).map((c) => `    ✓ ${c}`),
+            ...(f.tasks ?? []).map((t) => `    [${t.status}] ${t.key ?? t.id}: ${t.description}`),
+          ])
           .join("\n");
+        const goal = (list.goals ?? [])[0]?.title;
         return {
           content: [
             {
               type: "text",
-              text: `Plan revision ${list.baseRevision} — ${p.tasksDone}/${p.tasksTotal} tasks\n${rows || "(empty)"}`,
+              text:
+                `Plan revision ${list.baseRevision} — ${p.tasksDone}/${p.tasksTotal} tasks` +
+                `${goal ? `\nGoal: ${goal}` : ""}\n${rows || "(empty)"}`,
             },
           ],
           details: { revision: list.baseRevision, progress: p },
@@ -464,7 +520,12 @@ export default function (pi: ExtensionAPI): void {
         // writeTaskList takes the plan lock itself, around the whole
         // read-apply-write. Wrapping it again here would only add a second
         // lock with weaker semantics.
-        const result = writeTaskList(dir, { baseRevision: params.baseRevision, tasks: params.tasks! });
+        const result = writeTaskList(dir, {
+          baseRevision: params.baseRevision,
+          tasks: params.tasks,
+          features: params.features,
+          goal: params.goal,
+        });
         refreshWidget(ctx as ExtensionContext);
         return {
           content: [{ type: "text", text: summarizeApply(result) }],
@@ -678,6 +739,134 @@ export default function (pi: ExtensionAPI): void {
     },
   });
 
+  // -- init -----------------------------------------------------------------
+
+  /**
+   * Said wherever a command finds no harness.
+   *
+   * It used to be "No harness in this project." and nothing else — a dead end
+   * with no exit, in a tool whose every other command needs a harness to work.
+   * A warning that does not say what to do instead is only half a warning.
+   */
+  const NO_HARNESS = "No harness in this project yet. Run /infinity:init to create one.";
+
+  /** Everything the pipeline can run. INIT is not a phase you choose. */
+  const SELECTABLE_PHASES: Phase[] = ["define", "plan", "build", "verify", "simplify", "review", "ship"];
+
+  pi.registerTool({
+    name: "infinity_init",
+    label: "Init",
+    description:
+      "Create a harness in this project: config, an empty plan, the phase and role docs, and starters " +
+      "for the documents the review gate demands. Detects the stack and its lint/test/build commands. " +
+      "Refuses if a harness already exists unless force is set, and never overwrites an existing file.",
+    parameters: {
+      type: "object",
+      properties: {
+        mode: { type: "string", enum: ["copilot", "autopilot"], description: "copilot keeps the human in the loop" },
+        stack: { type: "string", enum: ["node", "python", "rust", "go", "unknown"] },
+        phases: {
+          type: "array",
+          items: { type: "string", enum: ["define", "plan", "build", "verify", "simplify", "review", "ship"] },
+          description: "Which phases run. Omit for the default pipeline.",
+        },
+        force: { type: "boolean", description: "Restore missing files in a project that already has a harness" },
+      },
+    } as never,
+    async execute(
+      _id: string,
+      params: { mode?: "copilot" | "autopilot"; stack?: StackId; phases?: Phase[]; force?: boolean },
+      _signal,
+      _onUpdate,
+      ctx,
+    ) {
+      const dir = projectDir(ctx);
+      const result = initHarness(dir, {
+        mode: params?.mode,
+        stack: params?.stack,
+        phases: params?.phases,
+        force: params?.force,
+      });
+      if (!result.ok) {
+        return {
+          content: [{ type: "text", text: result.error ?? "init failed" }],
+          details: result,
+          isError: true,
+        };
+      }
+      refreshWidget(ctx as ExtensionContext);
+      return { content: [{ type: "text", text: describeInit(result) }], details: result };
+    },
+  });
+
+  pi.registerCommand("infinity:init", {
+    description: "Create a harness in this project",
+    handler: async (args: string, ctx: ExtensionContext) => {
+      const dir = projectDir(ctx);
+      const force = /\bforce\b/.test(args);
+
+      if (isHarnessProject(dir) && !force) {
+        notify(
+          ctx,
+          "This project already has a harness. /infinity:config changes it; /infinity:init force restores missing files.",
+          "warning",
+        );
+        return;
+      }
+
+      const detected = detectStack(dir);
+      let mode: "copilot" | "autopilot" = "copilot";
+      let phases: Phase[] | undefined;
+
+      // With dialogs, ask the two questions whose answers we cannot infer.
+      // Without them, take the detected defaults and say so — an unattended
+      // run must not stall on a prompt nobody will answer.
+      if (ctx.hasUI) {
+        const cmds = Object.entries(detected.commands).filter(([, v]) => Boolean(v));
+        const summary = cmds.length ? cmds.map(([k, v]) => `${k}: ${v}`).join(", ") : "no commands detected";
+        const go = await ctx.ui.select(
+          `Create a harness here? ${detected.label} · ${summary}`,
+          ["yes, use these defaults", "yes, but let me choose the phases", "cancel"],
+        );
+        if (go === undefined || go === "cancel") {
+          notify(ctx, "init cancelled — nothing was written.", "info");
+          return;
+        }
+        const picked = await ctx.ui.select("How should it run?", [
+          "copilot — you stay in the loop",
+          "autopilot — it drives itself",
+        ]);
+        if (picked?.startsWith("autopilot")) mode = "autopilot";
+
+        if (go.includes("phases")) {
+          const chosen = new Set<Phase>(DEFAULT_ENABLED_PHASES);
+          for (;;) {
+            const rows = SELECTABLE_PHASES.map((p) => `${chosen.has(p) ? "[x]" : "[ ]"} ${p}`);
+            const hit = await ctx.ui.select("Phases to run", [...rows, "✓ done"]);
+            if (hit === undefined || hit === "✓ done") break;
+            const key = SELECTABLE_PHASES[rows.indexOf(hit)];
+            if (!key) break;
+            if (chosen.has(key)) chosen.delete(key);
+            else chosen.add(key);
+          }
+          phases = [...chosen];
+        }
+      }
+
+      const result = initHarness(dir, { mode, phases, force });
+      if (!result.ok) {
+        notify(ctx, result.error ?? "init failed", "error");
+        return;
+      }
+
+      notify(ctx, describeInit(result), "info");
+      refreshWidget(ctx);
+      // Hand the model the brief straight away, so the session that created
+      // the harness is also the session that starts using it.
+      pi.sendUserMessage(await briefText(dir), { deliverAs: "followUp" });
+    },
+  });
+
   // -- commands -------------------------------------------------------------
 
   pi.registerCommand("infinity:status", {
@@ -685,7 +874,7 @@ export default function (pi: ExtensionAPI): void {
     handler: async (_args: string, ctx: ExtensionContext) => {
       const dir = projectDir(ctx);
       if (!isHarnessProject(dir)) {
-        notify(ctx, "No harness in this project (harness/config.json not found).", "warning");
+        notify(ctx, NO_HARNESS, "warning");
         return;
       }
       const state = widgetStateFor(dir);
@@ -725,7 +914,7 @@ export default function (pi: ExtensionAPI): void {
     handler: async (_args: string, ctx: ExtensionContext) => {
       const dir = projectDir(ctx);
       if (!isHarnessProject(dir)) {
-        notify(ctx, "No harness in this project.", "warning");
+        notify(ctx, NO_HARNESS, "warning");
         return;
       }
       loopEnabled = true;
@@ -784,7 +973,7 @@ export default function (pi: ExtensionAPI): void {
     handler: async (args: string, ctx: ExtensionContext) => {
       const dir = projectDir(ctx);
       if (!isHarnessProject(dir)) {
-        notify(ctx, "No harness in this project (harness/config.json not found).", "warning");
+        notify(ctx, NO_HARNESS, "warning");
         return;
       }
 

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` — 12 scenarios over real temp projects, real git repos, real child processes: the
+- `npm run e2e` — 13 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/phases/define.md

@@ -27,14 +27,31 @@ feature list.
    - 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 `infinity_validate` to check gates
-10. If PASS → `infinity_advance` to advance to PLAN
+7. **Write the acceptance criteria into the plan** — this is what the DEFINE
+   gate actually checks. Every feature needs criteria before it opens:
+
+   ```jsonc
+   // infinity_plan
+   {
+     "goal": "one line: what this whole run is for",
+     "features": [
+       { "id": "feature-001", "name": "Checkout flow",
+         "criteria": ["refunds reconcile against the ledger"] }
+     ]
+   }
+   ```
+
+   Tasks are a separate list and arrive in PLAN — do not nest them here.
+   Criteria must be observable: "refunds reconcile against the ledger", not
+   "refunds work well". Put the evaluator hat on and ask whether passing these
+   would really prove the feature works.
+8. **Record the sprint contract** in `harness/sprint-contract.md` — scope,
+   what is explicitly out, and how you will know you are done. The gate does
+   not read it; the next session does.
+9. **Create a feature branch**: `git checkout -b feature/<short-slug>` (later
+   gates reject work on main/master)
+10. Run `infinity_validate` to check gates
+11. If PASS → `infinity_advance` to advance to PLAN
 
 ## Rationalizations to Avoid
 | Excuse | Rebuttal |
@@ -49,7 +66,8 @@ feature list.
 
 ## Verification
 - [ ] `specs/prd.md` exists with scope, success criteria, non-goals
-- [ ] Sprint contract agreed with non-placeholder verification criteria
+- [ ] Every feature has observable acceptance criteria in the plan
+- [ ] Sprint contract recorded in `harness/sprint-contract.md`
 - [ ] On a feature branch (not main/master)
 - [ ] Folder structure agreed and documented
 - [ ] `infinity_validate` passes

package/harness/docs/phases/ship.md

@@ -17,7 +17,7 @@ clean working tree, and ensure all ship gates pass.
 6. Ensure LICENSE, CONTRIBUTING.md exist
 7. Run `infinity_validate` to check ship gates
 8. If PASS → `infinity_advance` (pipeline complete!)
-9. Create checkpoint: `infinity-harness checkpoint create release-<version>`
+9. The release tag from step 5 is the checkpoint — nothing else to create.
 
 ## Rationalizations to Avoid
 | Excuse | Rebuttal |

package/harness/skills/code-review.md

@@ -25,8 +25,8 @@ the other.
 
 1. **Pin the fixed point.** `git diff <fixed-point>...HEAD` (three-dot) and
    `git log <fixed-point>..HEAD --oneline`. In the harness pipeline the fixed
-   point is usually the phase-start or sprint-start commit/tag
-   (`infinity-harness rollback list` shows checkpoints).
+   point is usually the phase-start or sprint-start commit or tag
+   (`git tag --sort=-creatordate | head` finds it).
 2. **Spec review.** The spec sources are `specs/prd.md`, the sprint contract
    (`harness/sprint-contract.md`), and the feature list's acceptance
    criteria. Report: (a) requirements missing or partial; (b) behaviour

package/harness/skills/context-hygiene.md

@@ -18,7 +18,7 @@ session (you, another agent, a human) starts from what was WRITTEN.
 
 - **Externalize at the moment of discovery**, not "later":
   - Surprise, gotcha, non-obvious behavior → `harness/lessons-decisions.md "..."`
-  - Design choice with a why → `infinity-harness decision "..."`
+  - Design choice with a why → `harness/docs/DECISIONS.md`
   - Resolved terminology → `harness/docs/DOMAIN.md`
   - Verified fact about an API/tool → `docs/research/` (with frontmatter)
 - **Re-read instead of remember.** Before acting on something you learned

package/harness/skills/diagnosing-bugs.md

@@ -82,4 +82,4 @@ pass → re-run the Phase 1 loop against the original scenario.
 - [ ] Record the confirmed hypothesis: `harness/lessons-decisions.md "bug X was caused by Y"`
 
 Then ask: what would have prevented this bug? If the answer is architectural
-(no test seam, tangled callers), record it: `infinity-harness decision "..."`.
+(no test seam, tangled callers), append it to `harness/docs/DECISIONS.md`.

package/harness/skills/domain-modeling.md

@@ -57,7 +57,8 @@ once `shipped`. NOT the same as a Cart (pre-checkout, mutable).
 scratch notes, no specs.
 
 ### Record decisions sparingly
-Record a decision (`infinity-harness decision "..."`) only when all three hold:
+Record a decision — one entry appended to `harness/docs/DECISIONS.md` — only
+when all three hold:
 
 1. **Hard to reverse** — changing your mind later costs something real
 2. **Surprising without context** — a future reader would ask "why?"

package/harness/skills/prototype.md

@@ -35,6 +35,6 @@ decides the shape:
 5. **Surface the state.** After every action, print the full relevant state
    so the effect of each step is visible.
 6. **Capture it when done.** Fold the validated decision into the real code
-   and record it: `infinity-harness decision "state machine X chosen because Y
-   (validated by prototype)"`. Then DELETE the prototype — the
+   and append it to `harness/docs/DECISIONS.md`: "state machine X chosen
+   because Y, validated by prototype". Then DELETE the prototype — the
    anti-placeholder gate will flag leftovers, and that's by design.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "infinity-harness",
-  "version": "2.0.4",
+  "version": "2.1.0",
   "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/gates.ts

@@ -196,7 +196,14 @@ async function checkNoPlaceholders({ targetDir, config }: Ctx): Promise<CheckRes
 function docCheck(name: string, path: string, minChars: number, hint: string): CheckResult {
   const text = readText(path);
   if (text === null) return fail(name, `${hint} is missing`);
-  const body = text.replace(/^#.*$/gm, "").trim();
+  // Headings are structure and HTML comments are instructions to the author —
+  // neither is content. This matters because the scaffolded starters explain
+  // in a comment what belongs in the file; counting that would let the review
+  // gate pass on a template nobody had written a word into.
+  const body = text
+    .replace(/<!--[\s\S]*?-->/g, "")
+    .replace(/^#.*$/gm, "")
+    .trim();
   return body.length >= minChars
     ? pass(name, `${hint} present (${body.length} chars)`)
     : fail(name, `${hint} exists but is essentially empty (${body.length} chars, need ${minChars})`);

package/src/core/init.ts

@@ -0,0 +1,379 @@
+/**
+ * infinity-harness — creating a harness in a project.
+ *
+ * Until this module existed there was no way to start. `pi install` put the
+ * extension in place, and then every command answered:
+ *
+ *   Warning: No harness in this project (harness/config.json not found).
+ *
+ * with nothing anywhere that would create one. The tool was, in the most
+ * literal sense, unusable out of the box.
+ *
+ * Init writes the smallest complete harness: the config, an empty plan, the
+ * phase and role docs the brief points at, and starters for the documents the
+ * REVIEW and SHIP gates demand.
+ *
+ * Those starters are deliberately shorter than the gate thresholds. It would
+ * be easy to scaffold an ARCHITECTURE.md long enough to satisfy
+ * `docCheck(..., 200)` on the day it is created — and that would mean the
+ * review gate passes on boilerplate nobody wrote. The whole design rests on
+ * the gate being unbribable; the setup step is not the place to hand it a
+ * bribe.
+ */
+
+import { existsSync, readFileSync, readdirSync, mkdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { HarnessConfig, Phase } from "./types.ts";
+import { DEFAULT_ENABLED_PHASES, PHASE_ORDER, PHASE_ROLE } from "./types.ts";
+import { defaultConfig, saveConfig } from "./config.ts";
+import { emptyFeatureList, saveFeatureList } from "./featureList.ts";
+import * as P from "./paths.ts";
+
+export type StackId = "node" | "python" | "rust" | "go" | "unknown";
+
+export type ProjectCommands = {
+  lint: string | null;
+  test: string | null;
+  coverage: string | null;
+  build: string | null;
+};
+
+export type DetectedStack = {
+  id: StackId;
+  label: string;
+  /** What gave it away, so the user can disagree with a reason. */
+  evidence: string;
+  commands: ProjectCommands;
+};
+
+const NO_COMMANDS: ProjectCommands = { lint: null, test: null, coverage: null, build: null };
+
+/**
+ * Work out what kind of project this is, and what its checks are.
+ *
+ * Only evidenced commands are proposed. Guessing `pytest` at a project that
+ * does not have pytest installed produces a gate that fails for a reason the
+ * user did not cause and cannot read — worse than proposing nothing, because
+ * an empty command is skipped and says so.
+ */
+export function detectStack(targetDir: string): DetectedStack {
+  const has = (f: string) => existsSync(resolve(targetDir, f));
+
+  if (has("package.json")) {
+    return { id: "node", label: "Node / TypeScript", evidence: "package.json", commands: nodeCommands(targetDir) };
+  }
+  if (has("Cargo.toml")) {
+    return {
+      id: "rust",
+      label: "Rust",
+      evidence: "Cargo.toml",
+      // cargo ships the same three verbs in every Rust project there is.
+      commands: {
+        lint: "cargo clippy -- -D warnings",
+        test: "cargo test",
+        coverage: null,
+        build: "cargo build",
+      },
+    };
+  }
+  if (has("go.mod")) {
+    return {
+      id: "go",
+      label: "Go",
+      evidence: "go.mod",
+      commands: { lint: "go vet ./...", test: "go test ./...", coverage: null, build: "go build ./..." },
+    };
+  }
+  if (has("pyproject.toml") || has("requirements.txt") || has("setup.py")) {
+    return {
+      id: "python",
+      label: "Python",
+      evidence: has("pyproject.toml") ? "pyproject.toml" : has("setup.py") ? "setup.py" : "requirements.txt",
+      commands: pythonCommands(targetDir),
+    };
+  }
+  return { id: "unknown", label: "unrecognised", evidence: "no manifest found", commands: { ...NO_COMMANDS } };
+}
+
+function nodeCommands(targetDir: string): ProjectCommands {
+  let scripts: Record<string, string> = {};
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(targetDir, "package.json"), "utf-8"));
+    if (pkg && typeof pkg.scripts === "object" && pkg.scripts) scripts = pkg.scripts;
+  } catch {
+    return { ...NO_COMMANDS };
+  }
+  const runner = existsSync(resolve(targetDir, "pnpm-lock.yaml"))
+    ? "pnpm"
+    : existsSync(resolve(targetDir, "yarn.lock"))
+      ? "yarn"
+      : existsSync(resolve(targetDir, "bun.lockb"))
+        ? "bun"
+        : "npm";
+  const run = (script: string) => (runner === "npm" ? `npm run ${script}` : `${runner} run ${script}`);
+  const first = (...names: string[]) => names.find((n) => typeof scripts[n] === "string");
+
+  const lint = first("lint", "check", "eslint");
+  const test = first("test", "test:unit", "tests");
+  const coverage = first("coverage", "test:coverage", "test:cov");
+  const build = first("build", "compile");
+  return {
+    lint: lint ? run(lint) : null,
+    test: test ? run(test) : null,
+    coverage: coverage ? run(coverage) : null,
+    build: build ? run(build) : null,
+  };
+}
+
+function pythonCommands(targetDir: string): ProjectCommands {
+  let pyproject = "";
+  try {
+    pyproject = readFileSync(resolve(targetDir, "pyproject.toml"), "utf-8");
+  } catch {
+    /* optional */
+  }
+  const hasTests = existsSync(resolve(targetDir, "tests")) || /\[tool\.pytest/.test(pyproject);
+  return {
+    lint: /\[tool\.ruff/.test(pyproject) ? "ruff check ." : null,
+    test: hasTests ? "pytest" : null,
+    coverage: null,
+    build: null,
+  };
+}
+
+export type InitOptions = {
+  stack?: StackId;
+  mode?: "copilot" | "autopilot";
+  phases?: Phase[];
+  commands?: Partial<ProjectCommands>;
+  /** Re-scaffold missing files in a project that already has a config. */
+  force?: boolean;
+};
+
+export type InitResult = {
+  ok: boolean;
+  error?: string;
+  /** Paths written, relative to the project. */
+  created: string[];
+  /** Paths left alone because they already existed. */
+  kept: string[];
+  config: HarnessConfig;
+  stack: DetectedStack;
+  /** The phase the pipeline now sits at. */
+  phase: Phase;
+};
+
+/**
+ * Create a harness in `targetDir`.
+ *
+ * Refuses an existing harness unless `force`, and even then never overwrites a
+ * file that is already there: someone's half-written ARCHITECTURE.md is worth
+ * more than our starter.
+ */
+export function initHarness(targetDir: string, options: InitOptions = {}): InitResult {
+  const stack = options.stack
+    ? { ...detectStack(targetDir), id: options.stack }
+    : detectStack(targetDir);
+
+  const created: string[] = [];
+  const kept: string[] = [];
+
+  const alreadyThere = existsSync(P.configPath(targetDir));
+  if (alreadyThere && !options.force) {
+    return {
+      ok: false,
+      error: "This project already has a harness. Use /infinity:config to change it, or re-run init with force to restore missing files.",
+      created,
+      kept,
+      config: defaultConfig(),
+      stack,
+      phase: "define",
+    };
+  }
+
+  const phases = normalizePhases(options.phases);
+  const phase = phases[0] ?? "define";
+
+  const config = defaultConfig();
+  config.stack = stack.id === "unknown" ? null : stack.id;
+  config.mode = options.mode ?? "copilot";
+  config.phases = { enabled: phases };
+  config.currentPhase = phase;
+  config.currentRole = PHASE_ROLE[phase];
+  config.commands = { ...stack.commands, ...stripUndefined(options.commands ?? {}) };
+
+  const write = (path: string, body: string) => {
+    const rel = path.slice(targetDir.length + 1);
+    if (existsSync(path)) {
+      kept.push(rel);
+      return;
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, body, "utf-8");
+    created.push(rel);
+  };
+
+  if (alreadyThere) {
+    kept.push("harness/config.json");
+  } else {
+    const saved = saveConfig(targetDir, config);
+    if (!saved.ok) {
+      return { ok: false, error: saved.error ?? "could not write harness/config.json", created, kept, config, stack, phase };
+    }
+    created.push("harness/config.json");
+  }
+
+  if (existsSync(P.featureListPath(targetDir))) {
+    kept.push("harness/features/feature-list.json");
+  } else {
+    saveFeatureList(targetDir, emptyFeatureList());
+    created.push("harness/features/feature-list.json");
+  }
+
+  // The brief points at these every phase; they are reference material, so
+  // they come from the package rather than being invented here.
+  copyPackagedDocs(targetDir, write);
+
+  write(P.architecturePath(targetDir), STARTER_ARCHITECTURE);
+  write(P.decisionsPath(targetDir), STARTER_DECISIONS);
+  write(P.constraintsPath(targetDir), STARTER_CONSTRAINTS);
+  write(resolve(P.docsDir(targetDir), "DOMAIN.md"), STARTER_DOMAIN);
+  write(P.rubricPath(targetDir), STARTER_RUBRIC);
+  write(P.lessonsPath(targetDir), STARTER_LESSONS);
+  write(resolve(P.harnessDir(targetDir), ".gitignore"), HARNESS_GITIGNORE);
+
+  return { ok: true, created, kept, config, stack, phase };
+}
+
+function stripUndefined<T extends object>(o: T): Partial<T> {
+  return Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined)) as Partial<T>;
+}
+
+/** Keep the caller's choice, but in pipeline order and without nonsense. */
+function normalizePhases(requested: Phase[] | undefined): Phase[] {
+  if (!requested || requested.length === 0) return [...DEFAULT_ENABLED_PHASES];
+  const wanted = new Set(requested.filter((p) => PHASE_ORDER.includes(p)));
+  wanted.delete("init");
+  const ordered = PHASE_ORDER.filter((p) => wanted.has(p));
+  return ordered.length ? [...ordered] : [...DEFAULT_ENABLED_PHASES];
+}
+
+/** Where the package keeps its own `harness/docs`. */
+export function packagedDocsDir(): string {
+  try {
+    return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "harness", "docs");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Copy the phase and role docs out of the package into the project.
+ *
+ * They are copied rather than read in place so the project can edit them —
+ * a team's BUILD doc should be able to say what BUILD means to them.
+ */
+function copyPackagedDocs(targetDir: string, write: (path: string, body: string) => void): void {
+  const src = packagedDocsDir();
+  if (!src || !existsSync(src)) return;
+  for (const sub of ["phases", "agents"]) {
+    const dir = join(src, sub);
+    if (!existsSync(dir)) continue;
+    let entries: string[];
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      continue;
+    }
+    for (const name of entries) {
+      if (!name.endsWith(".md")) continue;
+      const from = join(dir, name);
+      try {
+        if (!statSync(from).isFile()) continue;
+        write(join(P.docsDir(targetDir), sub, name), readFileSync(from, "utf-8"));
+      } catch {
+        /* one unreadable doc must not fail the whole init */
+      }
+    }
+  }
+}
+
+// ── Starters ────────────────────────────────────────────────────────────────
+//
+// Every one of these is under the gate's threshold on purpose. They tell you
+// what to write; they do not write it for you, because the gate that checks
+// them is the only referee this system has.
+
+const STARTER_ARCHITECTURE = `# Architecture
+
+<!-- The REVIEW gate wants 200+ characters of real content here. -->
+
+Modules, what each owns, and how data moves between them.
+`;
+
+const STARTER_DECISIONS = `# Decisions
+
+<!-- The REVIEW gate wants 100+ characters of real content here. -->
+
+One entry per decision: what was chosen, what was rejected, and why.
+`;
+
+const STARTER_CONSTRAINTS = `# Constraints
+
+What this project may not do, and what it must always do.
+`;
+
+const STARTER_DOMAIN = `# Domain
+
+Glossary only. One line per term, in the words the users of this system use.
+`;
+
+const STARTER_RUBRIC = `# Evaluator Rubric
+
+<!-- The REVIEW gate wants 100+ characters of real content here. -->
+
+What "good" means for this project, and how a reviewer scores it.
+`;
+
+const STARTER_LESSONS = `# Lessons and Decisions
+
+Append as you go: what surprised you, what you would do differently.
+`;
+
+const HARNESS_GITIGNORE = `# Run state — regenerated every run, never worth a diff.
+run-journal.jsonl
+STOP
+*.bak
+*.lock
+*.ilock
+.preflight
+.run-prompt.md
+
+# The plan, the config and the docs ARE worth committing: they are the
+# project's memory, and a harness without them starts from nothing.
+`;
+
+/** A human-readable summary of what init did. */
+export function describeInit(result: InitResult): string {
+  if (!result.ok) return result.error ?? "init failed";
+  const lines = [
+    `infinity-harness ready · ${result.stack.label} (${result.stack.evidence})`,
+    "",
+    `Phase     ${result.phase.toUpperCase()} — ${result.config.phases.enabled.join(" → ")}`,
+    `Mode      ${result.config.mode}`,
+  ];
+  const cmds = Object.entries(result.config.commands ?? {}).filter(([, v]) => Boolean(v));
+  lines.push(
+    cmds.length
+      ? `Commands  ${cmds.map(([k, v]) => `${k}: ${v}`).join("  ·  ")}`
+      : "Commands  none detected — set them with /infinity:config → Project commands",
+  );
+  lines.push("");
+  lines.push(`Created ${result.created.length} file(s) under harness/.`);
+  if (result.kept.length) lines.push(`Left ${result.kept.length} existing file(s) alone.`);
+  lines.push("");
+  lines.push("Next:  describe what you are building, then /infinity:next for the brief.");
+  lines.push("       /infinity:run hands it the wheel once there is a plan.");
+  return lines.join("\n");
+}

package/src/taskList.ts

@@ -49,9 +49,44 @@ export type TaskInput = {
   criteria?: string[];
 };
 
+/**
+ * Feature metadata, supplied alongside the tasks.
+ *
+ * Features themselves are derived from task keys — `feature-002/task-004`
+ * creates `feature-002` — which left no way at all to give a feature a name or
+ * its acceptance criteria. The DEFINE gate requires criteria on every feature,
+ * so the first gate in the pipeline could not be passed through the tools: the
+ * only route was hand-editing the plan file, which the brief tells you not to
+ * do.
+ *
+ * Unlike `tasks`, this is a merge and never a deletion. Omission means
+ * deletion for tasks because the model has to submit the authoritative list;
+ * features are not submitted at all, they are inferred, so omitting one here
+ * means "nothing to say about it", not "remove it".
+ */
+export type FeatureInput = {
+  id: string;
+  name?: string;
+  description?: string;
+  criteria?: string[];
+};
+
 export type ApplyInput = {
   baseRevision?: number;
-  tasks: TaskInput[];
+  /**
+   * The complete, authoritative task list. Omission means deletion — one
+   * unambiguous rule beats incremental edits a model loses track of.
+   *
+   * Leaving the whole field out is different from sending `[]`: absent means
+   * "I am not touching the tasks", empty means "delete them all". DEFINE needs
+   * that distinction, because criteria are written there and tasks do not
+   * exist until PLAN.
+   */
+  tasks?: TaskInput[];
+  /** Names and acceptance criteria, merged onto features by id. */
+  features?: FeatureInput[];
+  /** The one-line statement of what this whole run is for. */
+  goal?: string;
 };
 
 export type Change = {
@@ -96,6 +131,34 @@ function validateSubtasks(raw: TaskInput["subtasks"], path: string): Subtask[] {
   });
 }
 
+/** At most this many features may be described in one submission. */
+const MAX_FEATURES = 100;
+/** And this many acceptance criteria on any one of them. */
+const MAX_CRITERIA = 40;
+
+function bounded(value: string, max: number, path: string): string {
+  const trimmed = String(value ?? "").trim();
+  if (trimmed.length > max) {
+    throw new ValidationError(`${path} exceeds ${max} characters (${trimmed.length})`);
+  }
+  return trimmed;
+}
+
+function validateCriteria(raw: unknown, path: string): string[] {
+  if (!Array.isArray(raw)) throw new ValidationError(`${path} must be an array`);
+  if (raw.length > MAX_CRITERIA) {
+    throw new ValidationError(`${path} supports at most ${MAX_CRITERIA} entries, got ${raw.length}`);
+  }
+  const out: string[] = [];
+  for (const [i, entry] of raw.entries()) {
+    const text = bounded(String(entry ?? ""), MAX_SUBJECT_LEN, `${path}[${i}]`);
+    // An empty criterion is worse than none: it looks like the work was done.
+    if (!text) throw new ValidationError(`${path}[${i}] must be non-empty`);
+    if (!out.includes(text)) out.push(text);
+  }
+  return out;
+}
+
 function validateDependsOn(raw: string[] | undefined, path: string): string[] {
   if (!Array.isArray(raw)) return [];
   if (raw.length > MAX_DEPENDS_ON) {
@@ -126,11 +189,24 @@ export function applyTaskList(current: FeatureList, input: ApplyInput): ApplyRes
         `Re-read the plan and resubmit.`,
     );
   }
-  if (!Array.isArray(input.tasks)) {
+  if (input.tasks !== undefined && !Array.isArray(input.tasks)) {
     throw new ValidationError("tasks must be an array");
   }
-  if (input.tasks.length > MAX_TASKS) {
-    throw new ValidationError(`tasks supports at most ${MAX_TASKS} items, got ${input.tasks.length}`);
+  if (input.tasks === undefined && input.features === undefined && input.goal === undefined) {
+    throw new ValidationError("nothing submitted: send tasks, features, or a goal");
+  }
+  const inputFeatures = input.features;
+  const goal = input.goal;
+  if (inputFeatures !== undefined && !Array.isArray(inputFeatures)) {
+    throw new ValidationError("features must be an array");
+  }
+  if (Array.isArray(inputFeatures) && inputFeatures.length > MAX_FEATURES) {
+    throw new ValidationError(
+      `features supports at most ${MAX_FEATURES} items, got ${inputFeatures.length}`,
+    );
+  }
+  if ((input.tasks?.length ?? 0) > MAX_TASKS) {
+    throw new ValidationError(`tasks supports at most ${MAX_TASKS} items, got ${input.tasks!.length}`);
   }
 
   const before = flattenTasks(current);
@@ -146,8 +222,24 @@ export function applyTaskList(current: FeatureList, input: ApplyInput): ApplyRes
   const staged: Staged[] = [];
   const seen = new Set<string>();
 
-  for (let i = 0; i < input.tasks.length; i++) {
-    const raw = input.tasks[i]!;
+  // No `tasks` field means the submission is about features or the goal, and
+  // the task list carries over untouched. Re-staging what is already stored
+  // keeps every downstream step — dependency validation, the rebuild, the
+  // diff — on exactly one code path.
+  if (input.tasks === undefined) {
+    for (const f of current.features) {
+      for (const t of f.tasks ?? []) {
+        staged.push({
+          featureId: f.id,
+          task: structuredClone(t),
+          compositeKey: t.key ?? `${f.id}/${t.id}`,
+        });
+      }
+    }
+  }
+
+  for (let i = 0; i < (input.tasks?.length ?? 0); i++) {
+    const raw = input.tasks![i]!;
     const path = `tasks[${i}]`;
     const key = validateKey(String(raw?.key ?? ""), `${path}.key`);
     if (seen.has(key)) throw new ValidationError(`${path}.key is duplicated: ${key}`);
@@ -272,6 +364,60 @@ export function applyTaskList(current: FeatureList, input: ApplyInput): ApplyRes
     feature.tasks.push(s.task);
   }
 
+  // -- feature metadata -----------------------------------------------------
+  let metaChanged = false;
+  for (const [i, input] of (Array.isArray(inputFeatures) ? inputFeatures : []).entries()) {
+    const id = validateKey(input?.id ?? "", `features[${i}].id`);
+    // A model that has seen the plan file will reasonably try to nest tasks
+    // inside a feature. Silently dropping them would look like the write
+    // succeeded and lose the work; say where they go instead.
+    if ("tasks" in (input as object)) {
+      throw new ValidationError(
+        `features[${i}].tasks is not accepted — submit tasks in the top-level "tasks" array, ` +
+          `keyed "${id}/task-001". features carries names and criteria only.`,
+      );
+    }
+    let feature = featureById.get(id);
+    if (!feature) {
+      // Declaring a feature before its tasks exist is legitimate: DEFINE is
+      // where criteria are written, and PLAN is where tasks arrive.
+      feature = { id, name: id, passes: false, tasks: [] };
+      next.features.push(feature);
+      featureById.set(id, feature);
+      metaChanged = true;
+    }
+    if (typeof input.name === "string" && input.name.trim()) {
+      const name = bounded(input.name, MAX_SUBJECT_LEN, `features[${i}].name`);
+      if (feature.name !== name) {
+        feature.name = name;
+        metaChanged = true;
+      }
+    }
+    if (typeof input.description === "string") {
+      const description = bounded(input.description, MAX_SUBJECT_LEN, `features[${i}].description`);
+      if (feature.description !== description) {
+        feature.description = description;
+        metaChanged = true;
+      }
+    }
+    if (Array.isArray(input.criteria)) {
+      const criteria = validateCriteria(input.criteria, `features[${i}].criteria`);
+      if (JSON.stringify(feature.criteria ?? []) !== JSON.stringify(criteria)) {
+        feature.criteria = criteria;
+        metaChanged = true;
+      }
+    }
+  }
+
+  if (typeof goal === "string" && goal.trim()) {
+    const title = bounded(goal, MAX_SUBJECT_LEN, "goal");
+    const goals = Array.isArray(next.goals) ? next.goals : [];
+    if (goals[0]?.title !== title) {
+      next.goals = [{ ...(goals[0] ?? { id: "goal-001" }), title }, ...goals.slice(1)];
+      metaChanged = true;
+    }
+  }
+
   // A feature passes when it has tasks and all of them are complete.
   for (const f of next.features) {
     f.passes = f.tasks.length > 0 && f.tasks.every((t) => t.status === "complete");
@@ -295,7 +441,8 @@ export function applyTaskList(current: FeatureList, input: ApplyInput): ApplyRes
   const reordered =
     oldOrder.length !== newOrder.length || oldOrder.some((k, i) => k !== newOrder[i]);
 
-  const changed = added.length > 0 || updated.length > 0 || removed.length > 0 || reordered;
+  const changed =
+    added.length > 0 || updated.length > 0 || removed.length > 0 || reordered || metaChanged;
   next.baseRevision = changed ? current.baseRevision + 1 : current.baseRevision;
 
   return {