infinity-harness 2.2.0 → 2.3.0

package/harness/docs/agents/researcher.md

@@ -0,0 +1,14 @@
+# Researcher Role
+
+Tone: Curious and sceptical, in that order. Report what you found, not what you hoped.
+
+You establish what is true before anyone commits to what to build.
+
+- Read primary sources. A summary of a summary is a rumour
+- Separate what you were told from what you inferred — an inference is a question
+- Present at least two real options, with what each costs
+- Recommend one, and name what would make the recommendation wrong
+- End with the open questions only a human can answer; they are the DEFINE interview
+- Write findings to `harness/docs/RESEARCH.md` and nothing else — you do not
+  write code, choose a file layout, or open tasks
+- Hand off to Planner once a human could read your document and disagree with it

package/harness/docs/phases/research.md

@@ -0,0 +1,64 @@
+# RESEARCH Phase
+
+## Overview
+Turn an idea into evidence before anyone writes a specification. RESEARCH is
+optional and runs first, before DEFINE. Its output is one document —
+`harness/docs/RESEARCH.md` — that a human can read and disagree with.
+
+The phase exists because "build me a thing" is not a specification, and the
+cheapest hour of a long run is the one spent finding out what the thing has to
+be. A run that gets BUILD wrong fails a gate and retries. A run that got the
+idea wrong spends a weekend building the wrong product perfectly.
+
+## When to Use
+- The human gave an idea, not a specification
+- The problem has prior art worth reading before reinventing it
+- There is a real choice of approach and the trade-offs are not obvious
+- Skip it when the work is well understood — this phase is off by default
+
+## Craft Skills (read before working)
+- `harness/skills/research.md` — answer blocking factual questions from primary sources
+- `harness/skills/grilling.md` — attack your own conclusions before a human does
+- `harness/skills/scope-discipline.md` — research is not the place to start building
+
+## Process
+1. Restate the idea in your own words, including what you are *not* sure about.
+2. Find prior art. What already exists that does some of this? What did it get
+   right, and where does it stop?
+3. Name the constraints that are real: platform, data, budget, deadline, the
+   humans who will operate it. Say which ones you were told and which ones you
+   inferred, because an inferred constraint is a question for the human.
+4. Lay out the genuine options — at least two — with what each costs and what
+   each buys. An option list of one is a decision wearing a disguise.
+5. Recommend one, and say what would have to be true for the recommendation to
+   be wrong. That sentence is the most useful line in the document.
+6. List the open questions a human has to answer. These become the DEFINE
+   interview.
+7. Write all of it to `harness/docs/RESEARCH.md`.
+8. Run `infinity_validate`. On PASS the harness advances to DEFINE — or, if the
+   human asked to approve this phase, it stops and waits for their signature.
+
+## Rationalizations to Avoid
+| Excuse | Rebuttal |
+|--------|----------|
+| "I already know how to build this" | Then the phase costs you ten minutes and confirms it |
+| "I'll research as I go" | Research during BUILD arrives after the decisions it should have informed |
+| "There's no prior art" | There is. You have not looked yet |
+
+## Red Flags
+- A document with no open questions — you did not look hard enough
+- One option presented as inevitable
+- Findings with no source, stated as confidently as findings with one
+- Research that has already chosen the file layout: that is PLAN's job
+
+## Verification
+- [ ] `harness/docs/RESEARCH.md` exists and says something a human could argue with
+- [ ] Prior art named, not gestured at
+- [ ] At least two options, with costs
+- [ ] A recommendation, and what would falsify it
+- [ ] Open questions listed for DEFINE
+- [ ] `infinity_validate` passes
+
+## Handoff
+On gate pass: the harness advances to DEFINE (Researcher → Planner). The open
+questions from this document are the DEFINE interview.

package/harness/skills/grilling.md

@@ -3,7 +3,7 @@ name: grilling
 description: Stress-test a spec or plan with relentless one-at-a-time questions before committing
 tags: [grill, spec, requirements, questions, stress, interview, scope, clarify]
 when: before proposing the sprint contract, or when a plan feels underspecified
-phases: [define]
+phases: [research, define]
 kind: process
 provenance: { origin: "mattpocock/skills", license: MIT, adapted: true }
 ---

package/harness/skills/research.md

@@ -3,7 +3,7 @@ name: research
 description: Answer factual questions from primary sources; capture cited findings in the repo
 tags: [research, docs, documentation, investigate, source, facts, api, spec, evidence]
 when: a factual question about an API, library, protocol, or tool blocks progress
-phases: [define, plan, build]
+phases: [research, define, plan, build]
 kind: process
 provenance: { origin: "mattpocock/skills", license: MIT, adapted: true }
 ---

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "infinity-harness",
-  "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.",
+  "version": "2.3.0",
+  "description": "A pi agent extension that runs a gated build pipeline unattended — enforces phases, validates with deterministic gates, and keeps working for hours or days without losing the plan.",
   "type": "module",
   "keywords": [
     "pi-package",

package/src/approval.ts

@@ -0,0 +1,194 @@
+/**
+ * infinity-harness — human sign-off on the phases that decide what gets built.
+ *
+ * The gate is a good referee for execution and a poor one for intent. It can
+ * prove a feature has acceptance criteria; it cannot prove they are the right
+ * criteria. It can prove a plan has tasks; it cannot prove the plan builds the
+ * thing the human asked for. Those two judgements are the human's, and this
+ * module is where the run stops to collect them.
+ *
+ * The policy is per-phase and set once, by the start-up wizard:
+ *
+ *   copilot    RESEARCH (if on), DEFINE and PLAN are approved by the human
+ *   autopilot  the human picks which of them to approve and which to forfeit;
+ *              forfeiting all three is the "give it a goal and walk away" mode
+ *
+ * Nothing after PLAN is approvable. Once the definition and the plan are
+ * signed off, a wrong BUILD fails a gate and retries — a wrong DEFINE spends a
+ * weekend building the wrong product perfectly.
+ */
+
+import type { HarnessConfig, Phase } from "./core/types.ts";
+import { APPROVABLE_PHASES } from "./core/types.ts";
+import { loadConfig, saveConfig } from "./core/config.ts";
+
+export type ApprovalRequest = {
+  phase: Phase;
+  /** What the human is being asked to look at before signing. */
+  artifacts: string[];
+  prompt: string;
+};
+
+export function isApprovable(phase: Phase | null): boolean {
+  return phase !== null && (APPROVABLE_PHASES as readonly string[]).includes(phase);
+}
+
+/** Does `phase` need a signature before the pipeline may leave it? */
+export function needsApproval(config: HarnessConfig, phase: Phase | null): boolean {
+  if (!isApprovable(phase)) return false;
+  const approvals = (config.approvals ?? {}) as Record<string, unknown>;
+  return approvals[phase as string] === true;
+}
+
+/** Which phases the human has asked to sign, in pipeline order. */
+export function approvedPhases(config: HarnessConfig): Phase[] {
+  return APPROVABLE_PHASES.filter((p) => needsApproval(config, p)) as Phase[];
+}
+
+const ARTIFACTS: Record<string, string[]> = {
+  research: ["harness/docs/RESEARCH.md"],
+  define: ["specs/prd.md", "harness/sprint-contract.md", "the acceptance criteria in the plan"],
+  plan: ["the task list in the widget, or `/infinity:dashboard`"],
+};
+
+const ASKS: Record<string, string> = {
+  research:
+    "Does this research describe the problem you actually have, and is the recommendation one you would take?",
+  define:
+    "Is this the thing you want built, and would meeting these criteria convince you it works?",
+  plan: "Does this plan build that thing, in an order that makes sense, with nothing important missing?",
+};
+
+export function describeApproval(phase: Phase): ApprovalRequest {
+  return {
+    phase,
+    artifacts: ARTIFACTS[phase] ?? [],
+    prompt: ASKS[phase] ?? `Approve the ${phase.toUpperCase()} phase?`,
+  };
+}
+
+/** The text a human reads when the run pauses for them. */
+export function renderApprovalRequest(request: ApprovalRequest): string {
+  const lines = [
+    `${request.phase.toUpperCase()} passed its gate and is waiting for you.`,
+    "",
+    request.prompt,
+  ];
+  if (request.artifacts.length) {
+    lines.push("", "Look at:");
+    for (const a of request.artifacts) lines.push(`  - ${a}`);
+  }
+  lines.push(
+    "",
+    "`/infinity:approve` continues. `/infinity:approve <what is wrong>` sends it back",
+    "to be redone with your note. The run does not advance until you answer.",
+  );
+  return lines.join("\n");
+}
+
+/** Park the pipeline on `phase` until a human answers. */
+export function requestApproval(targetDir: string, phase: Phase): { ok: boolean; error: string | null } {
+  const { config, ok, error } = loadConfig(targetDir);
+  if (!ok) return { ok: false, error: error ?? "cannot load config" };
+  config.awaitingApproval = phase;
+  const saved = saveConfig(targetDir, config);
+  return { ok: saved.ok, error: saved.error };
+}
+
+/**
+ * A rejection, pinned to the state of the project when it was made.
+ *
+ * Without the fingerprint the run nags: the gate is deterministic, so the
+ * moment a phase is sent back it passes again on the next tick and asks the
+ * human the same question. Recording *what the project looked like* when they
+ * said no means the question is only asked again once something has actually
+ * changed in response to it.
+ */
+export type ApprovalRejection = { phase: string; note: string; fingerprint: string; at: string };
+
+export function loadRejection(config: HarnessConfig): ApprovalRejection | null {
+  const raw = config.approvalRejection as Partial<ApprovalRejection> | undefined;
+  if (!raw || typeof raw.phase !== "string" || typeof raw.fingerprint !== "string") return null;
+  return {
+    phase: raw.phase,
+    note: typeof raw.note === "string" ? raw.note : "",
+    fingerprint: raw.fingerprint,
+    at: typeof raw.at === "string" ? raw.at : "",
+  };
+}
+
+/**
+ * Has the project moved since the human said no?
+ *
+ * `true` means the agent has not yet done anything about the rejection, so
+ * re-asking would be asking the same question about the same artefact.
+ */
+export function rejectionStandsFor(
+  config: HarnessConfig,
+  phase: string,
+  fingerprint: string,
+): ApprovalRejection | null {
+  const rejection = loadRejection(config);
+  if (!rejection || rejection.phase !== phase) return null;
+  return rejection.fingerprint === fingerprint ? rejection : null;
+}
+
+export type ApprovalOutcome =
+  | { ok: true; approved: true; phase: Phase }
+  | { ok: true; approved: false; phase: Phase; note: string }
+  | { ok: false; error: string };
+
+/**
+ * Answer a pending approval.
+ *
+ * An empty note approves. A note is a rejection carrying the reason, which is
+ * the only useful form of "no": the phase is re-run with the human's words in
+ * the brief, rather than re-run identically and failing the same way.
+ */
+export function resolveApproval(
+  targetDir: string,
+  note = "",
+  fingerprint = "",
+): ApprovalOutcome {
+  const { config, ok, error } = loadConfig(targetDir);
+  if (!ok) return { ok: false, error: error ?? "cannot load config" };
+
+  const phase = config.awaitingApproval;
+  if (!phase) return { ok: false, error: "Nothing is waiting for approval." };
+
+  config.awaitingApproval = null;
+  const trimmed = note.trim();
+  if (trimmed) {
+    const notes = Array.isArray(config.approvalNotes) ? (config.approvalNotes as unknown[]) : [];
+    config.approvalNotes = [
+      ...notes,
+      { phase, note: trimmed, at: new Date().toISOString() },
+    ].slice(-50);
+    config.approvalRejection = { phase, note: trimmed, fingerprint, at: new Date().toISOString() };
+  } else {
+    // Approved. The old rejection is answered, and the note that carried it
+    // must stop appearing in the brief — an agent told to address a complaint
+    // that was already resolved goes round in circles fixing nothing.
+    config.approvalRejection = null;
+    config.approvalNotes = (Array.isArray(config.approvalNotes) ? config.approvalNotes : []).filter(
+      (n) => typeof n === "object" && n !== null && (n as { phase?: unknown }).phase !== phase,
+    );
+  }
+
+  const saved = saveConfig(targetDir, config);
+  if (!saved.ok) return { ok: false, error: saved.error ?? "could not save config" };
+
+  return trimmed
+    ? { ok: true, approved: false, phase, note: trimmed }
+    : { ok: true, approved: true, phase };
+}
+
+/** Notes the human left when rejecting a phase, newest last. */
+export function approvalNotes(config: HarnessConfig, phase?: Phase): { phase: string; note: string; at: string }[] {
+  const raw = Array.isArray(config.approvalNotes) ? config.approvalNotes : [];
+  const all = raw.filter(
+    (n): n is { phase: string; note: string; at: string } =>
+      typeof n === "object" && n !== null && typeof (n as { note?: unknown }).note === "string",
+  );
+  return phase ? all.filter((n) => n.phase === phase) : all;
+}

package/src/core/brief.ts

@@ -42,6 +42,8 @@ const SKILL_SUGGESTIONS = 2;
 
 const PHASE_INTENT: Record<Phase, string> = {
   init: "Set up the project skeleton and confirm the harness can see it.",
+  research:
+    "Find out what this actually has to be. Prior art, constraints, options with costs, a recommendation, and the questions only the human can answer. Write harness/docs/RESEARCH.md. No code.",
   define: "Write down what is being built and how you will know it is done. Acceptance criteria per feature.",
   plan: "Break each feature into ordered, dependency-aware tasks. No code yet.",
   build: "Implement the current task. One task at a time, tests alongside.",
@@ -66,6 +68,25 @@ export async function buildBrief(targetDir: string, options: BuildBriefOptions =
   const notes: string[] = [];
   if (!ok) notes.push("harness/config.json is missing or unreadable — run init.");
 
+  // The human rejected this phase and said why. Repeating the phase without
+  // repeating their words produces the same output and the same rejection.
+  if (phase) {
+    const rejections = rejectionNotes(config, phase);
+    const last = rejections[rejections.length - 1];
+    if (last) {
+      notes.push(
+        `A human reviewed ${phase.toUpperCase()} and sent it back. Address this before validating again: ${last.note}`,
+      );
+    }
+  }
+
+  if (config.awaitingApproval) {
+    notes.push(
+      `${String(config.awaitingApproval).toUpperCase()} is waiting for a human signature. ` +
+        "Do not start the next phase — stop and let them answer.",
+    );
+  }
+
   const nextTask = nextActionableTask(list);
   const feature = nextTask ? findFeature(list, nextTask.featureId) : null;
 
@@ -108,7 +129,11 @@ export async function buildBrief(targetDir: string, options: BuildBriefOptions =
     role,
     paused: Boolean(config.paused),
     complete,
-    goal: (list.goals ?? [])[0]?.title ?? null,
+    // The plan's goal is what the agent wrote down; the intake brief is what
+    // the human actually said. Before a plan exists, the second is all there
+    // is — and a run that starts with neither invents its own scope, which is
+    // exactly the failure this field was added to stop.
+    goal: (list.goals ?? [])[0]?.title ?? intakeBrief(config),
     feature: feature ? { id: feature.id, name: feature.name } : null,
     task: nextTask
       ? {
@@ -134,7 +159,7 @@ export async function buildBrief(targetDir: string, options: BuildBriefOptions =
       max: retry.tasks.max,
     },
     skills: suggestSkills(phase, {
-      goal: (list.goals ?? [])[0]?.title ?? null,
+      goal: (list.goals ?? [])[0]?.title ?? intakeBrief(config),
       feature: feature?.name ?? null,
       task: nextTask?.description ?? null,
       criteria: collectCriteria(feature, nextTask?.criteria),
@@ -166,6 +191,30 @@ function suggestSkills(
   }
 }
 
+/**
+ * Notes a human left when they sent a phase back.
+ *
+ * Read here rather than imported from `src/approval.ts` on purpose: `core/`
+ * owns the config file format and must not depend on the layer above it.
+ */
+function rejectionNotes(config: HarnessConfig, phase: Phase): { note: string }[] {
+  const raw = Array.isArray(config.approvalNotes) ? config.approvalNotes : [];
+  return raw.filter(
+    (n): n is { phase: string; note: string } =>
+      typeof n === "object" &&
+      n !== null &&
+      (n as { phase?: unknown }).phase === phase &&
+      typeof (n as { note?: unknown }).note === "string",
+  );
+}
+
+/** What the human typed into the start-up wizard, if anything. */
+function intakeBrief(config: HarnessConfig): string | null {
+  const intake = config.intake as { brief?: unknown } | undefined;
+  const brief = intake?.brief;
+  return typeof brief === "string" && brief.trim() ? brief.trim() : null;
+}
+
 function collectCriteria(
   feature: { criteria?: string[] } | null,
   taskCriteria: string[] | undefined,

package/src/core/config.ts

@@ -8,7 +8,7 @@
  */
 
 import type { HarnessConfig, GateHistoryEntry, Phase, Role } from "./types.ts";
-import { DEFAULT_ENABLED_PHASES } from "./types.ts";
+import { DEFAULT_ENABLED_PHASES, PHASE_ROLE } from "./types.ts";
 import { configPath } from "./paths.ts";
 import { readJson, writeJsonAtomic, backupOnce, fileExists } from "./fsx.ts";
 
@@ -49,6 +49,10 @@ export function defaultConfig(): HarnessConfig {
     },
     phases: { enabled: [...DEFAULT_ENABLED_PHASES] },
     roles: { strict: false },
+    session: { handoff: "phase", contextThreshold: 0.7, carryNotes: true },
+    approvals: { research: false, define: false, plan: false },
+    intake: { completed: false, brief: null, at: null },
+    awaitingApproval: null,
     loop: {
       maxIterations: 2000,
       maxWallClockMs: 24 * 60 * 60 * 1000,
@@ -159,6 +163,25 @@ export function recordGate(
     ...(scope?.feature ? { feature: scope.feature } : {}),
     ...(scope?.task ? { task: scope.task } : {}),
   };
+
+  // Two callers record the same *pass*: `runChecks` when the gate is run, and
+  // `transitionPhase` when that verdict lets the pipeline leave the phase. The
+  // history read `research:pass → research:pass → define:pass → define:pass`,
+  // which reads as a phase that had to be attempted twice — the opposite of
+  // what happened. The same pass is not two passes.
+  //
+  // Repeated *failures* are never collapsed: five failures on one phase is
+  // exactly the fact a human comes back to read.
+  const last = config.gateHistory[config.gateHistory.length - 1];
+  const duplicatePass =
+    result === "pass" &&
+    last !== undefined &&
+    last.phase === entry.phase &&
+    last.result === "pass" &&
+    (last.feature ?? null) === (entry.feature ?? null) &&
+    (last.task ?? null) === (entry.task ?? null);
+  if (duplicatePass) return;
+
   config.gateHistory.push(entry);
   trimGateHistory(config);
 }
@@ -249,17 +272,13 @@ export function validateConfig(config: HarnessConfig): string[] {
   return missing;
 }
 
+/**
+ * The role that owns a phase.
+ *
+ * This used to be a second copy of `PHASE_ROLE` written out longhand, which
+ * meant adding a phase compiled fine and then silently reported the wrong
+ * role for it. There is one table.
+ */
 export function currentRoleFor(phase: Phase | null): Role | null {
-  if (!phase) return null;
-  const map: Record<Phase, Role> = {
-    init: "planner",
-    define: "planner",
-    plan: "planner",
-    build: "generator",
-    verify: "evaluator",
-    simplify: "simplifier",
-    review: "evaluator",
-    ship: "evaluator",
-  };
-  return map[phase] ?? null;
+  return phase ? (PHASE_ROLE[phase] ?? null) : null;
 }

package/src/core/fsx.ts

@@ -13,6 +13,7 @@ import {
   mkdirSync,
   readFileSync,
   renameSync,
+  rmSync,
   unlinkSync,
   writeFileSync,
   copyFileSync,
@@ -117,3 +118,12 @@ export function backupOnce(path: string): void {
 export function fileExists(path: string): boolean {
   return existsSync(path);
 }
+
+/** Delete a file if it is there. Never throws — a missing file is the goal. */
+export function removeFile(path: string): void {
+  try {
+    if (existsSync(path)) rmSync(path, { force: true });
+  } catch {
+    /* a file we cannot delete is the caller's problem, not a crash */
+  }
+}

package/src/core/gates.ts

@@ -221,6 +221,20 @@ async function checkLicense({ targetDir }: Ctx): Promise<CheckResult> {
 async function checkChangelog({ targetDir }: Ctx): Promise<CheckResult> {
   return docCheck("changelog", resolve(targetDir, "CHANGELOG.md"), 100, "CHANGELOG.md");
 }
+/**
+ * RESEARCH produced something a human could read and disagree with.
+ *
+ * The research phase exists because "build me a thing" is not a specification,
+ * and the cheapest hour of a long run is the one spent finding out what the
+ * thing actually has to be. The gate asks for evidence of that hour: prior
+ * art, constraints, options weighed, a recommendation. 400 characters is a low
+ * bar deliberately — the gate judges that work happened, the human judges
+ * whether it was any good.
+ */
+async function checkResearchDoc({ targetDir }: Ctx): Promise<CheckResult> {
+  return docCheck("research-doc", P.researchPath(targetDir), 400, "harness/docs/RESEARCH.md");
+}
+
 async function checkArchitectureDoc({ targetDir }: Ctx): Promise<CheckResult> {
   return docCheck("architecture-doc", P.architecturePath(targetDir), 200, "harness/docs/ARCHITECTURE.md");
 }
@@ -345,6 +359,7 @@ type Check = (ctx: Ctx) => Promise<CheckResult>;
 
 const PHASE_CHECKS: Record<Phase, Check[]> = {
   init: [checkGitRepo, checkConfigExists],
+  research: [checkResearchDoc],
   define: [checkFeatureCriteria, checkSkillsLoad],
   plan: [checkFeatureCriteria, checkTasksPlanned],
   build: [checkLint, checkTests, checkCoverage, checkNoPlaceholders, checkTasksComplete],

package/src/core/init.ts

@@ -149,6 +149,12 @@ export type InitOptions = {
   commands?: Partial<ProjectCommands>;
   /** Re-scaffold missing files in a project that already has a config. */
   force?: boolean;
+  /** Which phases stop for a human signature. See SessionPolicy / ApprovalPolicy. */
+  approvals?: Partial<HarnessConfig["approvals"]>;
+  /** Session-handoff policy. Defaults to a fresh session per phase. */
+  session?: Partial<HarnessConfig["session"]>;
+  /** What the human said they want built. Recorded, and read by the first brief. */
+  brief?: string | null;
 };
 
 export type InitResult = {
@@ -202,6 +208,15 @@ export function initHarness(targetDir: string, options: InitOptions = {}): InitR
   config.currentPhase = phase;
   config.currentRole = PHASE_ROLE[phase];
   config.commands = { ...stack.commands, ...stripUndefined(options.commands ?? {}) };
+  config.approvals = { ...config.approvals, ...stripUndefined(options.approvals ?? {}) };
+  config.session = { ...config.session, ...stripUndefined(options.session ?? {}) };
+  if (options.brief !== undefined) {
+    config.intake = {
+      completed: true,
+      brief: options.brief && options.brief.trim() ? options.brief.trim() : null,
+      at: new Date().toISOString(),
+    };
+  }
 
   const write = (path: string, body: string) => {
     const rel = path.slice(targetDir.length + 1);
@@ -236,6 +251,7 @@ export function initHarness(targetDir: string, options: InitOptions = {}): InitR
   copyPackagedDocs(targetDir, write);
 
   write(P.architecturePath(targetDir), STARTER_ARCHITECTURE);
+  if (phases.includes("research")) write(P.researchPath(targetDir), STARTER_RESEARCH);
   write(P.decisionsPath(targetDir), STARTER_DECISIONS);
   write(P.constraintsPath(targetDir), STARTER_CONSTRAINTS);
   write(resolve(P.docsDir(targetDir), "DOMAIN.md"), STARTER_DOMAIN);
@@ -312,6 +328,20 @@ const STARTER_ARCHITECTURE = `# Architecture
 Modules, what each owns, and how data moves between them.
 `;
 
+const STARTER_RESEARCH = `# Research
+
+<!--
+The RESEARCH gate wants 400+ characters of real content here, outside headings
+and comments. Write what you found, not what you plan to do:
+
+  Prior art       what already exists, what it gets right, where it stops
+  Constraints     which were given, which you inferred (an inference is a question)
+  Options         at least two, with what each costs and what each buys
+  Recommendation  one of them, and what would have to be true for it to be wrong
+  Open questions  the ones only a human can answer — these become the DEFINE interview
+-->
+`;
+
 const STARTER_DECISIONS = `# Decisions
 
 <!-- The REVIEW gate wants 100+ characters of real content here. -->
@@ -373,7 +403,18 @@ export function describeInit(result: InitResult): string {
   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.");
+
+  // The old copy said "describe what you are building" — advice from before
+  // the wizard asked for that up front. Telling a human to do a thing they
+  // have already done is how they learn to stop reading the output.
+  const goal = (result.config.intake as { brief?: unknown } | undefined)?.brief;
+  if (typeof goal === "string" && goal.trim()) {
+    lines.push(`Goal      ${goal.trim()}`);
+    lines.push("");
+    lines.push(`Next:  /infinity:run hands it the wheel. /infinity:next prints the brief first.`);
+  } else {
+    lines.push("Next:  say what you are building — the run will ask before it does anything.");
+    lines.push("       /infinity:run hands it the wheel once there is a plan.");
+  }
   return lines.join("\n");
 }

package/src/core/paths.ts

@@ -69,10 +69,24 @@ export function decisionsPath(targetDir: string): string {
   return resolve(docsDir(targetDir), "DECISIONS.md");
 }
 
+export function researchPath(targetDir: string): string {
+  return resolve(docsDir(targetDir), "RESEARCH.md");
+}
+
 export function constraintsPath(targetDir: string): string {
   return resolve(docsDir(targetDir), "CONSTRAINTS.md");
 }
 
+/** Whether a continuous run is armed, and which run it is. Survives sessions. */
+export function runStatePath(targetDir: string): string {
+  return resolve(harnessDir(targetDir), "run.json");
+}
+
+/** A handoff waiting to be picked up by the session that replaces this one. */
+export function pendingSessionPath(targetDir: string): string {
+  return resolve(harnessDir(targetDir), "next-session.json");
+}
+
 export function skillsDir(targetDir: string): string {
   return resolve(harnessDir(targetDir), "skills");
 }