infinity-harness 2.0.4 → 2.2.0

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` — 15 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.2.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/brief.ts

@@ -87,6 +87,20 @@ export async function buildBrief(targetDir: string, options: BuildBriefOptions =
     notes.push(`${blockedTasks.length} task(s) are blocked: ${blockedTasks.map((t) => t.compositeKey).join(", ")}`);
   }
 
+  // A second pass at a goal is not the same as a first pass at one, and the
+  // agent has no way to tell unless the brief says so. Without this the model
+  // re-plans from scratch and rebuilds what the last review already accepted.
+  const remaining = Array.isArray(config.remainingWork)
+    ? (config.remainingWork as unknown[]).filter((w): w is string => typeof w === "string" && w.trim() !== "")
+    : [];
+  if (remaining.length > 0) {
+    const pass = typeof config.goalPass === "number" ? `pass ${config.goalPass}` : "this pass";
+    notes.push(
+      `The goal was reviewed and judged not yet met. ${remaining.length} item(s) remain for ${pass} — ` +
+        `plan for these, not for the whole goal again: ${remaining.join("; ")}`,
+    );
+  }
+
   const complete = isFinalPhase(phase, config.phases?.enabled) && progress.tasksDone === progress.tasksTotal;
 
   return {

package/src/core/gates.ts

@@ -12,12 +12,13 @@
  */
 
 import { resolve } from "node:path";
-import { readdirSync, statSync } from "node:fs";
+import { existsSync, readdirSync, statSync } from "node:fs";
 import type { CheckResult, GateResult, HarnessConfig, Phase } from "./types.ts";
 import { loadConfig, saveConfig, recordGate } from "./config.ts";
 import { loadFeatureList, findTask, findFeature, computeProgress, isDone } from "./featureList.ts";
 import * as P from "./paths.ts";
 import { readText, fileExists } from "./fsx.ts";
+import { auditSkillsDir } from "./skillsAudit.ts";
 import {
   run,
   isGitRepo,
@@ -196,7 +197,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})`);
@@ -223,6 +231,39 @@ async function checkRubricContent({ targetDir }: Ctx): Promise<CheckResult> {
   return docCheck("rubric-content", P.rubricPath(targetDir), 100, "harness/evaluator-rubric.md");
 }
 
+/**
+ * Any skills this project ships must be loadable by pi.
+ *
+ * Advisory, because a malformed skill does not make the code wrong — it makes
+ * pi print a `[Skill conflicts]` block on every start, which is exactly the
+ * kind of thing that gets ignored for months. This package learned that the
+ * hard way from its own README sitting in its own skills directory. Reporting
+ * it in the gate is how a project finds out before its users do.
+ */
+async function checkSkillsLoad({ targetDir }: Ctx): Promise<CheckResult> {
+  const dirs = [P.skillsDir(targetDir), resolve(targetDir, ".pi", "skills"), resolve(targetDir, ".agents", "skills")];
+  const present = dirs.filter((d) => existsSync(d));
+  if (present.length === 0) {
+    return { ...skip("skills-load", "this project ships no skills"), advisory: true };
+  }
+
+  const problems: string[] = [];
+  let count = 0;
+  for (const dir of present) {
+    const audit = auditSkillsDir(dir);
+    count += audit.skills.length;
+    for (const p of audit.problems) {
+      problems.push(`${p.file.replace(`${targetDir}/`, "")}: ${p.message}`);
+    }
+  }
+  return problems.length === 0
+    ? { ...pass("skills-load", `${count} skill(s) load cleanly in pi`), advisory: true }
+    : {
+        ...fail("skills-load", `pi would report a skill conflict — ${problems.slice(0, 4).join("; ")}`),
+        advisory: true,
+      };
+}
+
 async function checkTagged({ targetDir }: Ctx): Promise<CheckResult> {
   return (await gitHasTag(targetDir))
     ? pass("tagged", "HEAD carries a release tag")
@@ -304,12 +345,12 @@ type Check = (ctx: Ctx) => Promise<CheckResult>;
 
 const PHASE_CHECKS: Record<Phase, Check[]> = {
   init: [checkGitRepo, checkConfigExists],
-  define: [checkFeatureCriteria],
+  define: [checkFeatureCriteria, checkSkillsLoad],
   plan: [checkFeatureCriteria, checkTasksPlanned],
   build: [checkLint, checkTests, checkCoverage, checkNoPlaceholders, checkTasksComplete],
   verify: [checkTests, checkCoverage, checkGitClean],
   simplify: [checkTests, checkNoEmptyDirs, checkGitClean],
-  review: [checkBranchUpToDate, checkRubricContent, checkReadme, checkArchitectureDoc, checkDecisionsLogged],
+  review: [checkBranchUpToDate, checkRubricContent, checkReadme, checkArchitectureDoc, checkDecisionsLogged, checkSkillsLoad],
   ship: [
     checkGitClean,
     checkTagged,

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");
+}