feat(run-once): integrate planning phases and require implementation pull requests

src/cli/commands/run-once/development-environment-agent.ts

@@ -0,0 +1,108 @@
+import { resolve } from "node:path";
+import {
+  profileExtensionArgs,
+  runOnceDevelopmentEnvironmentPiProfile,
+} from "../../../pi/resource-profiles.ts";
+import { parseDevelopmentEnvironmentResult, runPiPrompt } from "./pi.ts";
+import { buildDevelopmentEnvironmentPrompt } from "./prompts.ts";
+import type {
+  AgentIssueConfig,
+  AgentIssueDevelopmentEnvironmentHandoff,
+  AgentIssueDevelopmentEnvironmentNotReadyResult,
+  AgentIssueProgressEvent,
+  CommandRunner,
+  IssueSummary,
+  ProgressReporter,
+} from "./types.ts";
+
+export type DevelopmentEnvironmentAgentOutcome =
+  | { kind: "ready"; handoff: AgentIssueDevelopmentEnvironmentHandoff }
+  | {
+      kind: "not-ready";
+      result: AgentIssueDevelopmentEnvironmentNotReadyResult;
+    };
+
+export type DevelopmentEnvironmentAgentInput = {
+  runner: CommandRunner;
+  config: AgentIssueConfig;
+  issue: IssueSummary;
+  labels: string[];
+  planPath: string;
+  branch: string;
+  worktreePath: string;
+  completedAt: string;
+  piAgentDir: string;
+  tokenUsageState: { total: number };
+  progressReporter?: ProgressReporter | undefined;
+  streamPiOutput?: ((chunk: string) => void) | undefined;
+  verbosePiOutput?: boolean | undefined;
+  heartbeatMs?: number | undefined;
+  piSessionPath?: string | undefined;
+  progress: (
+    level: AgentIssueProgressEvent["level"],
+    stage: string,
+    message: string,
+    extras?: Partial<Pick<AgentIssueProgressEvent, "issueNumber">>,
+  ) => Promise<void>;
+  runStep: <T>(label: string, fn: () => Promise<T>) => Promise<T>;
+  observePi: (
+    stage: "pi-development-environment",
+  ) => (observation: AgentIssueProgressEvent["observation"]) => Promise<void>;
+};
+
+export async function runDevelopmentEnvironmentAgent(
+  input: DevelopmentEnvironmentAgentInput,
+): Promise<DevelopmentEnvironmentAgentOutcome> {
+  const developmentEnvironmentSkill =
+    input.config.skills.developmentEnvironment;
+  if (!developmentEnvironmentSkill)
+    throw new Error(
+      "Development environment stage requires skills.developmentEnvironment",
+    );
+  const worktreeRoot = resolve(input.config.repoRoot, input.worktreePath);
+  const profile = runOnceDevelopmentEnvironmentPiProfile(
+    input.config.skills,
+    input.config.repoRoot,
+  );
+  const result = await input.runStep("development environment", async () => {
+    await input.progress(
+      "info",
+      "development-environment",
+      "running development environment with pi",
+      { issueNumber: input.issue.number },
+    );
+    return runPiPrompt(
+      input.runner,
+      worktreeRoot,
+      buildDevelopmentEnvironmentPrompt({
+        issue: { ...input.issue, labels: input.labels },
+        planPath: input.planPath,
+        branch: input.branch,
+        worktreePath: input.worktreePath,
+        projectPolicy: input.config.projectPolicy,
+        skills: input.config.skills,
+      }),
+      {
+        progress: input.progressReporter,
+        stage: "pi-development-environment",
+        parseResult: parseDevelopmentEnvironmentResult,
+        skillPaths: profile.additionalSkillPaths,
+        extensionArgs: profileExtensionArgs(profile),
+        streamOutput: input.streamPiOutput,
+        issueNumber: input.issue.number,
+        repoRoot: worktreeRoot,
+        heartbeatMs: input.heartbeatMs,
+        tokenUsageState: input.tokenUsageState,
+        observeSession: true,
+        sessionRoot: input.piSessionPath,
+        verbosePiOutput: input.verbosePiOutput,
+        onObservation: input.observePi("pi-development-environment"),
+        taskContract: input.config.projectPolicy.pi.taskContract,
+        piAgentDir: input.piAgentDir,
+      },
+    );
+  });
+  return result.status === "not-ready"
+    ? { kind: "not-ready", result }
+    : { kind: "ready", handoff: { ...result, completedAt: input.completedAt } };
+}

src/cli/commands/run-once/development-environment-stage.ts

@@ -1,12 +1,6 @@
-import { join } from "node:path";
-import {
-  profileExtensionArgs,
-  runOnceDevelopmentEnvironmentPiProfile,
-} from "../../../pi/resource-profiles.ts";
 import type { IssueHostProvider } from "../../../host/types.ts";
 import { planLabelChange } from "../triage/labels.ts";
-import { parseDevelopmentEnvironmentResult, runPiPrompt } from "./pi.ts";
-import { buildDevelopmentEnvironmentPrompt } from "./prompts.ts";
+import { runDevelopmentEnvironmentAgent } from "./development-environment-agent.ts";
 import { writeRunState } from "./run-state.ts";
 import { retryableLabelsAfterDevelopmentEnvironmentFailure } from "./workflow-state.ts";
 import type {
@@ -33,37 +27,38 @@ type DevelopmentEnvironmentDetails = {
   worktreePath: string;
 };
 
-type DevelopmentEnvironmentStageOptions = DevelopmentEnvironmentDetails & {
-  runner: CommandRunner;
-  host: IssueHostProvider;
-  config: AgentIssueConfig;
-  issue: IssueSummary;
-  labels: string[];
-  readyLabel: string;
-  inProgressLabel: string;
-  timestamp: string;
-  logPath?: string;
-  piSessionPath?: string;
-  streamPiOutput?: (chunk: string) => void;
-  verbosePiOutput?: boolean;
-  heartbeatMs?: number;
-  piAgentDir: string;
-  tokenUsageState: { total: number };
-  progressReporter?: ProgressReporter | undefined;
-  progress: (
-    level: AgentIssueProgressEvent["level"],
-    stage: string,
-    message: string,
-    extras?: Partial<
-      Pick<AgentIssueProgressEvent, "issueNumber" | "elapsedSeconds" | "data">
-    >,
-  ) => Promise<void>;
-  runStep: <T>(label: string, fn: () => Promise<T>) => Promise<T>;
-  observePi: (
-    stage: "pi-development-environment",
-  ) => (observation: AgentIssueProgressEvent["observation"]) => Promise<void>;
-  emitSimpleStep: (issueNumber: number, label: string) => Promise<void>;
-};
+export type DevelopmentEnvironmentStageOptions =
+  DevelopmentEnvironmentDetails & {
+    runner: CommandRunner;
+    host: IssueHostProvider;
+    config: AgentIssueConfig;
+    issue: IssueSummary;
+    labels: string[];
+    readyLabel: string;
+    inProgressLabel: string;
+    timestamp: string;
+    logPath?: string;
+    piSessionPath?: string;
+    streamPiOutput?: (chunk: string) => void;
+    verbosePiOutput?: boolean;
+    heartbeatMs?: number;
+    piAgentDir: string;
+    tokenUsageState: { total: number };
+    progressReporter?: ProgressReporter | undefined;
+    progress: (
+      level: AgentIssueProgressEvent["level"],
+      stage: string,
+      message: string,
+      extras?: Partial<
+        Pick<AgentIssueProgressEvent, "issueNumber" | "elapsedSeconds" | "data">
+      >,
+    ) => Promise<void>;
+    runStep: <T>(label: string, fn: () => Promise<T>) => Promise<T>;
+    observePi: (
+      stage: "pi-development-environment",
+    ) => (observation: AgentIssueProgressEvent["observation"]) => Promise<void>;
+    emitSimpleStep: (issueNumber: number, label: string) => Promise<void>;
+  };
 
 function withLogPath<T extends AgentIssuePipelineResult>(
   result: T,
@@ -79,7 +74,7 @@ function withLogPath<T extends AgentIssuePipelineResult>(
   };
 }
 
-async function developmentEnvironmentNotReady(
+export async function developmentEnvironmentNotReady(
   options: DevelopmentEnvironmentStageOptions,
   result: Extract<
     AgentIssueDevelopmentEnvironmentResult,
@@ -149,73 +144,30 @@ async function developmentEnvironmentNotReady(
 export async function runDevelopmentEnvironmentStage(
   options: DevelopmentEnvironmentStageOptions,
 ): Promise<DevelopmentEnvironmentStageResult> {
-  const developmentEnvironmentSkill =
-    options.config.skills.developmentEnvironment;
-  if (!developmentEnvironmentSkill) {
-    throw new Error(
-      "Development environment stage requires skills.developmentEnvironment",
-    );
-  }
-
-  const worktreeRoot = join(options.config.repoRoot, options.worktreePath);
-  const profile = runOnceDevelopmentEnvironmentPiProfile(
-    options.config.skills,
-    options.config.repoRoot,
-  );
-  const result = await options.runStep(
-    "development environment",
-    async (): Promise<AgentIssueDevelopmentEnvironmentResult> => {
-      await options.progress(
-        "info",
-        "development-environment",
-        "running development environment with pi",
-        { issueNumber: options.issue.number },
-      );
-      return await runPiPrompt(
-        options.runner,
-        worktreeRoot,
-        buildDevelopmentEnvironmentPrompt({
-          issue: { ...options.issue, labels: options.labels },
-          planPath: options.planPath,
-          branch: options.branch,
-          worktreePath: options.worktreePath,
-          projectPolicy: options.config.projectPolicy,
-          skills: options.config.skills,
-        }),
-        {
-          progress: options.progressReporter,
-          stage: "pi-development-environment",
-          parseResult: parseDevelopmentEnvironmentResult,
-          skillPaths: profile.additionalSkillPaths,
-          extensionArgs: profileExtensionArgs(profile),
-          streamOutput: options.streamPiOutput,
-          issueNumber: options.issue.number,
-          repoRoot: worktreeRoot,
-          heartbeatMs: options.heartbeatMs,
-          tokenUsageState: options.tokenUsageState,
-          observeSession: true,
-          sessionRoot: options.piSessionPath,
-          verbosePiOutput: options.verbosePiOutput,
-          onObservation: options.observePi("pi-development-environment"),
-          taskContract: options.config.projectPolicy.pi.taskContract,
-          piAgentDir: options.piAgentDir,
-        },
-      );
-    },
-  );
-
-  if (result.status === "not-ready") {
+  const result = await runDevelopmentEnvironmentAgent({
+    runner: options.runner,
+    config: options.config,
+    issue: options.issue,
+    labels: options.labels,
+    planPath: options.planPath,
+    branch: options.branch,
+    worktreePath: options.worktreePath,
+    completedAt: options.timestamp,
+    piAgentDir: options.piAgentDir,
+    tokenUsageState: options.tokenUsageState,
+    progressReporter: options.progressReporter,
+    streamPiOutput: options.streamPiOutput,
+    verbosePiOutput: options.verbosePiOutput,
+    heartbeatMs: options.heartbeatMs,
+    piSessionPath: options.piSessionPath,
+    progress: options.progress,
+    runStep: options.runStep,
+    observePi: options.observePi,
+  });
+  if (result.kind === "not-ready")
     return {
       kind: "not-ready",
-      result: await developmentEnvironmentNotReady(options, result),
+      result: await developmentEnvironmentNotReady(options, result.result),
     };
-  }
-
-  return {
-    kind: "ready",
-    handoff: {
-      ...result,
-      completedAt: options.timestamp,
-    },
-  };
+  return result;
 }

src/cli/commands/run-once/implementation-agent.test.ts

@@ -0,0 +1,57 @@
+import assert from "node:assert/strict";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import test from "node:test";
+import { createMockRunner } from "../../../../test-support/run-once/mock-runner.ts";
+import { makeConfig } from "../../../../test-support/run-once/pipeline-fixtures.ts";
+import { runImplementationAgent } from "./implementation-agent.ts";
+
+test("returns a merged Pi result without applying direct-land policy", async () => {
+  const config = await makeConfig({ dryRun: false, execute: true });
+  const worktreePath = ".worktrees/issue-189";
+  await mkdir(join(config.repoRoot, worktreePath), { recursive: true });
+  const planPath = "docs/plans/issue-189.md";
+  await mkdir(join(config.repoRoot, "docs/plans"), { recursive: true });
+  await writeFile(join(config.repoRoot, planPath), "# plan\n", "utf8");
+  const runner = createMockRunner(async (call) => {
+    if (call.command === "pi")
+      return {
+        code: 0,
+        stdout: JSON.stringify({
+          status: "merged",
+          mergeCommit: "a".repeat(40),
+          branch: "agent/issue-189",
+          commits: ["a".repeat(40)],
+          validation: ["npm test"],
+        }),
+        stderr: "",
+      };
+    throw new Error(`unexpected ${call.command}`);
+  });
+  const outcome = await runImplementationAgent({
+    runner,
+    config: {
+      ...config,
+      skills: { ...config.skills, developmentEnvironment: undefined },
+    },
+    issue: { number: 189, title: "Core", body: "", labels: [], state: "open" },
+    labels: [],
+    planPath,
+    branch: "agent/issue-189",
+    worktreePath,
+    worktree: { created: true, existingCommits: [] },
+    git: { baseBranch: "main", remote: "origin", allowDirectLand: false },
+    resume: { resumed: false },
+    piAgentDir: join(config.repoRoot, ".patchmill/pi-agent"),
+    tokenUsageState: { total: 0 },
+    completedAt: "2026-09-10T00:00:00.000Z",
+    progress: async () => {},
+    runStep: async (_label, fn) => fn(),
+    stepStart: async () => {},
+    stepComplete: async () => {},
+    observePi: () => async () => {},
+  });
+  assert.equal(outcome.kind, "implemented");
+  if (outcome.kind === "implemented")
+    assert.equal(outcome.result.status, "merged");
+});