supipowers 1.5.3 → 2.0.0

package/src/ultraplan/authoring/pipeline.ts

@@ -0,0 +1,319 @@
+/**
+ * Pipeline driver for the multi-stage authoring flow.
+ *
+ * Resolves the next stage to run from the manifest's `authoring` block, executes it via the
+ * stage's runner, and either advances or surfaces a gate decision to the caller. The driver
+ * is intentionally pure orchestration \u2014 every disk write goes through `authoring/storage`.
+ *
+ * Three gate modes:
+ *  - `default`: gates at discover, synthesize, approve.
+ *  - `auto`:    no user gates; runs end-to-end. Synthesize still produces a draft and the
+ *               approve stage promotes it without a user confirmation.
+ *  - `manual`:  every stage waits for explicit advance commands.
+ */
+
+import * as fs from "node:fs";
+
+import type { Platform, PlatformPaths } from "../../platform/types.js";
+import type {
+  ModelConfig,
+  UltraPlanAuthoringStage,
+} from "../../types.js";
+
+import { ApproveStage } from "./stages/approve.js";
+import { DiscoverStage } from "./stages/discover.js";
+import { IntakeStage } from "./stages/intake.js";
+import { ResearchStage } from "./stages/research.js";
+import { ReviewStage } from "./stages/review.js";
+import { ScoutStage } from "./stages/scout.js";
+import { SynthesizeStage } from "./stages/synthesize.js";
+import {
+  loadAuthoringState,
+} from "./storage.js";
+import type {
+  StageRunResult,
+  StageRunner,
+  StageRunnerContext,
+} from "./stage-runner.js";
+import { runSynthGateLoop } from "./synth-gate.js";
+import {
+  getUltraplanAuthoringDecisionsPath,
+  getUltraplanAuthoringDir,
+  getUltraplanAuthoringIntakePath,
+  getUltraplanAuthoringResearchSummaryPath,
+  getUltraplanAuthoringScoutPath,
+} from "../project-paths.js";
+
+export type PipelineGateMode = "default" | "auto" | "manual";
+
+const GATE_STAGES_DEFAULT = new Set<UltraPlanAuthoringStage>(["discover", "synthesize", "approve"]);
+const GATE_STAGES_MANUAL = new Set<UltraPlanAuthoringStage>([
+  "intake",
+  "scout",
+  "discover",
+  "research",
+  "synthesize",
+  "review",
+  "approve",
+]);
+
+export interface PipelineDriverInput {
+  platform: Platform;
+  paths: PlatformPaths;
+  cwd: string;
+  sessionId: string;
+  modelConfig: ModelConfig;
+  /** Required for INTAKE stage; ignored once intake artifact exists. */
+  seedPrompt: string;
+  gates: PipelineGateMode;
+  /** Iteration to use for review/approve. Defaults to 1. */
+  iteration?: number;
+}
+
+export interface PipelineRunOutcome {
+  /** Final stage that was executed (or attempted). */
+  stage: UltraPlanAuthoringStage;
+  status: StageRunResult["status"];
+  /** True when the pipeline reached APPROVE successfully. */
+  promoted: boolean;
+  /** Error or blocker message, when status is failed/blocked. */
+  message?: string;
+  /** Human-readable summary of every stage that ran. */
+  trace: { stage: UltraPlanAuthoringStage; status: StageRunResult["status"] }[];
+}
+
+interface ResolvedNextStage {
+  stage: UltraPlanAuthoringStage;
+  reason: "fresh-start" | "next-after-completed" | "resume-incomplete";
+}
+
+/**
+ * Find the stage that should run next for a session. Reads the manifest's `authoring` block;
+ * falls back to disk artifact existence for sessions that were started by a different driver
+ * version that didn't persist the manifest block.
+ */
+export function resolveNextStage(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): ResolvedNextStage {
+  const stateResult = loadAuthoringState(paths, cwd, sessionId);
+  if (stateResult.ok && stateResult.value) {
+    const state = stateResult.value;
+    if (state.stageStatus === "running") {
+      return { stage: state.stage, reason: "resume-incomplete" };
+    }
+    if (state.stageStatus === "blocked" || state.stageStatus === "awaiting-user") {
+      return { stage: state.stage, reason: "resume-incomplete" };
+    }
+    // status === "done" \u2014 advance to the next stage.
+    const next = nextStageOf(state.stage);
+    if (next) return { stage: next, reason: "next-after-completed" };
+    return { stage: "approve", reason: "next-after-completed" };
+  }
+
+  // Fall back to disk artifact existence.
+  if (!fs.existsSync(getUltraplanAuthoringIntakePath(paths, cwd, sessionId))) {
+    return { stage: "intake", reason: "fresh-start" };
+  }
+  if (!fs.existsSync(getUltraplanAuthoringScoutPath(paths, cwd, sessionId))) {
+    return { stage: "scout", reason: "resume-incomplete" };
+  }
+  if (!fs.existsSync(getUltraplanAuthoringDecisionsPath(paths, cwd, sessionId))) {
+    return { stage: "discover", reason: "resume-incomplete" };
+  }
+  if (!fs.existsSync(getUltraplanAuthoringResearchSummaryPath(paths, cwd, sessionId))) {
+    return { stage: "research", reason: "resume-incomplete" };
+  }
+  return { stage: "synthesize", reason: "resume-incomplete" };
+}
+
+function nextStageOf(stage: UltraPlanAuthoringStage): UltraPlanAuthoringStage | null {
+  switch (stage) {
+    case "intake":
+      return "scout";
+    case "scout":
+      return "discover";
+    case "discover":
+      return "research";
+    case "research":
+      return "synthesize";
+    case "synthesize":
+      return "review";
+    case "review":
+      return "approve";
+    case "approve":
+      return null;
+  }
+}
+
+/**
+ * Run a single stage by name. Used both by the full driver and by the per-stage CLI
+ * subcommands (`/supi:ultraplan discover`, `/supi:ultraplan research`, etc).
+ */
+export async function runStage(
+  stage: UltraPlanAuthoringStage,
+  input: Omit<PipelineDriverInput, "gates">,
+): Promise<StageRunResult> {
+  const ctx: StageRunnerContext = {
+    platform: input.platform,
+    paths: input.paths,
+    cwd: input.cwd,
+    sessionId: input.sessionId,
+    modelConfig: input.modelConfig,
+  };
+  const runner = buildRunner(stage, input);
+  return runner.run(ctx);
+}
+
+function buildRunner(
+  stage: UltraPlanAuthoringStage,
+  input: Omit<PipelineDriverInput, "gates">,
+): StageRunner {
+  switch (stage) {
+    case "intake":
+      return new IntakeStage({ seedPrompt: input.seedPrompt });
+    case "scout":
+      return new ScoutStage();
+    case "discover":
+      return new DiscoverStage();
+    case "research":
+      return new ResearchStage();
+    case "synthesize":
+      return new SynthesizeStage();
+    case "review":
+      return new ReviewStage({ iteration: input.iteration ?? 1 });
+    case "approve":
+      return new ApproveStage({ iteration: input.iteration ?? 1 });
+  }
+}
+
+function gateStagesFor(mode: PipelineGateMode): Set<UltraPlanAuthoringStage> {
+  switch (mode) {
+    case "default":
+      return GATE_STAGES_DEFAULT;
+    case "auto":
+      return new Set();
+    case "manual":
+      return GATE_STAGES_MANUAL;
+  }
+}
+
+/**
+ * Run the pipeline forward until either (a) it completes through APPROVE, (b) it lands at a
+ * gate stage, or (c) a stage returns `failed`/`blocked`. Synth-stage gating includes the
+ * `$EDITOR` round-trip via `runSynthGateLoop`.
+ *
+ * The driver does **not** run interactive UI prompts on its own \u2014 the calling command
+ * orchestrator wraps the call and presents `ctx.ui.select` / `ctx.ui.confirm` between
+ * driver invocations.
+ */
+export async function runPipelineUntilGate(input: PipelineDriverInput): Promise<PipelineRunOutcome> {
+  const trace: { stage: UltraPlanAuthoringStage; status: StageRunResult["status"] }[] = [];
+  const gateStages = gateStagesFor(input.gates);
+
+  let safety = 0;
+  // Hard cap to prevent runaway loops if a runner ever returns `completed` without advancing
+  // its on-disk state. We've sized this to handle the longest legitimate path (intake \u2192 scout
+  // \u2192 discover \u2192 research \u2192 synthesize \u2192 review \u2192 approve = 7) plus a margin.
+  while (safety < 16) {
+    safety += 1;
+    const next = resolveNextStage(input.paths, input.cwd, input.sessionId);
+    const runner = buildRunner(next.stage, input);
+    const ctx: StageRunnerContext = {
+      platform: input.platform,
+      paths: input.paths,
+      cwd: input.cwd,
+      sessionId: input.sessionId,
+      modelConfig: input.modelConfig,
+    };
+
+    const result = await runner.run(ctx);
+    trace.push({ stage: next.stage, status: result.status });
+
+    if (result.status === "failed" || result.status === "blocked") {
+      return {
+        stage: next.stage,
+        status: result.status,
+        promoted: false,
+        message: result.error ?? result.blocker?.message,
+        trace,
+      };
+    }
+
+    // Synth-stage editor round-trip when in non-manual modes. After the planner draft is
+    // persisted, run the editor gate; on save, the driver continues to review.
+    if (next.stage === "synthesize" && result.status === "awaiting-user" && input.gates !== "manual") {
+      const gate = await runSynthGateLoop({
+        platform: input.platform,
+        paths: input.paths,
+        cwd: input.cwd,
+        sessionId: input.sessionId,
+        iteration: input.iteration ?? 1,
+      });
+      if (gate.status === "io-error" || gate.status === "parse-failed") {
+        return {
+          stage: next.stage,
+          status: "blocked",
+          promoted: false,
+          message: gate.status === "parse-failed"
+            ? `Synth gate parse-failed after retries: ${gate.errors.map((e) => e.message).join("; ")}`
+            : gate.message,
+          trace,
+        };
+      }
+    }
+
+    if (gateStages.has(next.stage) && result.status !== "skipped") {
+      // Awaiting user gate: caller orchestrates the prompt and re-invokes the driver.
+      return {
+        stage: next.stage,
+        status: "awaiting-user",
+        promoted: false,
+        trace,
+      };
+    }
+
+    if (next.stage === "approve" && (result.status === "completed" || result.status === "skipped")) {
+      return {
+        stage: "approve",
+        status: result.status,
+        promoted: true,
+        trace,
+      };
+    }
+  }
+
+  return {
+    stage: "approve",
+    status: "failed",
+    promoted: false,
+    message: "Pipeline driver exceeded its safety cap; check the manifest's authoring block for inconsistency.",
+    trace,
+  };
+}
+
+/**
+ * Detect every in-flight authoring session for the picker. Returns sessions whose manifest
+ * has an `authoring` block AND whose canonical authored.json doesn't exist yet (i.e. they
+ * haven't been promoted).
+ */
+export function listInFlightAuthoringSessions(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionIds: string[],
+): { sessionId: string; stage: UltraPlanAuthoringStage; status: string }[] {
+  const inFlight = [];
+  for (const sessionId of sessionIds) {
+    const dir = getUltraplanAuthoringDir(paths, cwd, sessionId);
+    if (!fs.existsSync(dir)) continue;
+    const stateResult = loadAuthoringState(paths, cwd, sessionId);
+    if (!stateResult.ok || !stateResult.value) continue;
+    inFlight.push({
+      sessionId,
+      stage: stateResult.value.stage,
+      status: stateResult.value.stageStatus,
+    });
+  }
+  return inFlight;
+}

package/src/ultraplan/authoring/stage-runner.ts

@@ -0,0 +1,141 @@
+/**
+ * Stage runner abstraction for the multi-stage authoring pipeline.
+ *
+ * Every stage runs as a fresh `platform.createAgentSession`. The stage runner is the thin
+ * wrapper that:
+ *  - resolves the model + agent prompt for the stage,
+ *  - builds the assignment prompt deterministically from prior artifacts,
+ *  - spawns the session and awaits its completion (the agent calls one or more
+ *    `ultraplan_*` tools, which the hook bridge translates into atomic disk writes),
+ *  - transitions the manifest's `authoring` block on success.
+ *
+ * This file owns the abstract interface only. Concrete stages live under `stages/`.
+ *
+ * Design notes:
+ *  - Stages do not share state in memory. The disk artifacts under `<session>/authoring/`
+ *    are the source of truth. `resume` is just `run` with the same inputs — which means
+ *    we always re-derive prompts from disk, never from in-memory variables.
+ *  - Each stage owns its own pre-flight check (`isReady`) and post-condition
+ *    (`isComplete`). The pipeline driver uses these to decide whether to skip, run,
+ *    or block.
+ *  - Errors propagate as `StageRunResult` discriminated unions. Stage runners never throw
+ *    on user-visible failures (validation, missing prerequisites, agent abort). They throw
+ *    only on programming errors (malformed config, etc.).
+ */
+
+import type { Platform } from "../../platform/types.js";
+import type { PlatformPaths } from "../../platform/types.js";
+import type {
+  ModelConfig,
+  UltraPlanAuthoringStage,
+  UltraPlanAuthoringStageStatus,
+  UltraPlanBlocker,
+} from "../../types.js";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/**
+ * Inputs available to every stage runner. The runner reads from disk inside `run` rather
+ * than capturing state at construction time, which keeps `resume` semantics trivial.
+ */
+export interface StageRunnerContext {
+  platform: Platform;
+  paths: PlatformPaths;
+  cwd: string;
+  sessionId: string;
+  /** Loaded once at the start of the pipeline; passed in for model resolution. */
+  modelConfig: ModelConfig;
+  /**
+   * Optional override for `now()` so tests can produce deterministic timestamps. Production
+   * code defaults to `Date.now()` via `() => new Date().toISOString()`.
+   */
+  now?: () => string;
+  /** Optional override for the agent session model. Tests use this to bypass resolution. */
+  modelOverride?: { model: string; thinkingLevel: string | null };
+}
+
+export type StageRunStatus =
+  | "completed"     // The stage ran to completion and persisted its artifact.
+  | "skipped"       // Pre-conditions said the stage was already done; no work performed.
+  | "blocked"       // The stage hit a structured blocker; manifest's `authoring.blocker` set.
+  | "awaiting-user" // The stage produced output but needs a user gate before advancing.
+  | "failed";       // Programming-level failure; surfaced for the operator with `error`.
+
+export interface StageRunResult {
+  status: StageRunStatus;
+  stage: UltraPlanAuthoringStage;
+  /** Artifacts touched by this run (relative to `<session>/authoring/`). */
+  artifactPaths: string[];
+  /** Set when status is `blocked`. */
+  blocker?: UltraPlanBlocker;
+  /** Set when status is `failed`. */
+  error?: string;
+  /** Free-form structured details for `pipeline-log.jsonl`. */
+  details?: Record<string, unknown>;
+}
+
+export interface StageRunner {
+  /** The stage this runner advances. Constant per runner. */
+  readonly stage: UltraPlanAuthoringStage;
+
+  /**
+   * Cheap existence check: are the upstream artifacts the stage needs available on disk?
+   * The pipeline driver calls this before `run` to bucket sessions in the resume picker.
+   */
+  isReady(ctx: StageRunnerContext): Promise<boolean>;
+
+  /**
+   * Has this stage already been completed for the given session? Used by `resume` to
+   * decide whether to re-run or skip. Returns `true` if the stage's primary artifact
+   * exists on disk and passes its schema validation.
+   */
+  isComplete(ctx: StageRunnerContext): Promise<boolean>;
+
+  /**
+   * Execute the stage. Idempotent: if `isComplete` returns true, the runner returns
+   * `status: "skipped"` without spawning an agent. Otherwise it runs the agent, awaits
+   * completion, validates the produced artifact, and updates the manifest's
+   * `authoring.stage` / `stageStatus` fields atomically.
+   */
+  run(ctx: StageRunnerContext): Promise<StageRunResult>;
+}
+
+// ---------------------------------------------------------------------------
+// Convenience helpers shared by concrete stages
+// ---------------------------------------------------------------------------
+
+export function nowIso(ctx: StageRunnerContext): string {
+  return (ctx.now ?? (() => new Date().toISOString()))();
+}
+
+/**
+ * Build a deterministic agent display name for the spawned `createAgentSession`. The
+ * convention `ultraplan-authoring-<stage>[/<discriminator>]` lets the picker and logs
+ * correlate sessions to stages without parsing prompts.
+ */
+export function buildAgentDisplayName(
+  stage: UltraPlanAuthoringStage,
+  discriminator?: string,
+): string {
+  return discriminator ? `ultraplan-authoring-${stage}/${discriminator}` : `ultraplan-authoring-${stage}`;
+}
+
+/**
+ * Translate a `StageRunStatus` to the manifest's `stageStatus` value for the same stage.
+ */
+export function toManifestStageStatus(status: StageRunStatus): UltraPlanAuthoringStageStatus {
+  switch (status) {
+    case "completed":
+      return "done";
+    case "skipped":
+      return "done";
+    case "blocked":
+      return "blocked";
+    case "awaiting-user":
+      return "awaiting-user";
+    case "failed":
+      return "blocked";
+  }
+}