supipowers 1.5.3 → 2.0.1

package/src/ultraplan/authoring/stages/approve.ts

@@ -0,0 +1,249 @@
+/**
+ * APPROVE stage runner.
+ *
+ * Deterministic disk-only operation — no agent is spawned. Promotes an approved draft to
+ * canonical artifacts: writes `authored.json`, `manifest.json` (with `authoring` block
+ * cleared and `state: "ready"`), updates `index.json`, and renders `authored.md`.
+ *
+ * Resume semantics: skipped when `<session>/authored.json` already exists and the
+ * manifest's `authoring` block is absent (i.e., the promotion already happened).
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { persistAuthoredUltraPlanSession } from "../../authoring-persist.js";
+import { validateUltraPlanAuthoredArtifact } from "../../contracts.js";
+import {
+  getUltraplanAuthoredJsonPath,
+  getUltraplanAuthoredMarkdownPath,
+  getUltraplanAuthoringDraftAuthoredJsonPath,
+  getUltraplanAuthoringDraftFindingsPath,
+  ULTRAPLAN_AUTHORED_JSON_FILENAME,
+  ULTRAPLAN_AUTHORED_MARKDOWN_FILENAME,
+} from "../../project-paths.js";
+import { loadUltraPlanManifest } from "../../storage.js";
+import { appendPipelineLog, loadDraftAuthoredJson } from "../storage.js";
+import {
+  nowIso,
+  toManifestStageStatus,
+  type StageRunResult,
+  type StageRunner,
+  type StageRunnerContext,
+} from "../stage-runner.js";
+import type { UltraPlanAuthoredArtifact } from "../../../types.js";
+
+// ---------------------------------------------------------------------------
+// Public input
+// ---------------------------------------------------------------------------
+
+export interface ApproveStageInput {
+  /** Which iteration's draft to promote. Must match an existing `drafts/iteration-N/` dir. */
+  iteration: number;
+}
+
+// ---------------------------------------------------------------------------
+// Markdown renderer
+// ---------------------------------------------------------------------------
+
+/**
+ * Produce a simple human-readable summary of the authored artifact. No external helper
+ * exists in the codebase yet, so this renderer is inline.
+ */
+function renderApprovedMarkdown(authored: UltraPlanAuthoredArtifact): string {
+  const lines: string[] = [
+    `# ${authored.title}`,
+    ``,
+    `**Goal:** ${authored.goal}`,
+    ``,
+  ];
+
+  const applicable = authored.stacks.filter((s) => s.applicability === "applicable");
+  if (applicable.length > 0) {
+    lines.push(`## Stacks`);
+    lines.push(``);
+    for (const stack of applicable) {
+      const count = stack.domains.reduce(
+        (n, d) => n + d.unit.length + d.integration.length + d.e2e.length,
+        0,
+      );
+      lines.push(`### ${stack.stack}`);
+      lines.push(``);
+      for (const domain of stack.domains) {
+        const domainCount =
+          domain.unit.length + domain.integration.length + domain.e2e.length;
+        lines.push(
+          `- **${domain.name}** (${domainCount} scenario${domainCount === 1 ? "" : "s"})`,
+        );
+        for (const scenario of [...domain.unit, ...domain.integration, ...domain.e2e]) {
+          lines.push(`  - ${scenario.title}`);
+        }
+      }
+      lines.push(``);
+      lines.push(
+        `_${count} total scenario${count === 1 ? "" : "s"}_`,
+      );
+      lines.push(``);
+    }
+  }
+
+  lines.push(`---`);
+  lines.push(`_Session ID: ${authored.sessionId}_`);
+  lines.push(``);
+
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Stage implementation
+// ---------------------------------------------------------------------------
+
+export class ApproveStage implements StageRunner {
+  readonly stage = "approve" as const;
+
+  constructor(private readonly input: ApproveStageInput) {}
+
+  async isReady(ctx: StageRunnerContext): Promise<boolean> {
+    const draftPath = getUltraplanAuthoringDraftAuthoredJsonPath(
+      ctx.paths, ctx.cwd, ctx.sessionId, this.input.iteration,
+    );
+    const findingsPath = getUltraplanAuthoringDraftFindingsPath(
+      ctx.paths, ctx.cwd, ctx.sessionId, this.input.iteration,
+    );
+    return fs.existsSync(draftPath) && fs.existsSync(findingsPath);
+  }
+
+  async isComplete(ctx: StageRunnerContext): Promise<boolean> {
+    const authoredPath = getUltraplanAuthoredJsonPath(ctx.paths, ctx.cwd, ctx.sessionId);
+    if (!fs.existsSync(authoredPath)) return false;
+    const manifestResult = loadUltraPlanManifest(ctx.paths, ctx.cwd, ctx.sessionId);
+    if (!manifestResult.ok) return false;
+    // Complete when the authoring block has been cleared (promotion succeeded).
+    return !manifestResult.value.authoring;
+  }
+
+  async run(ctx: StageRunnerContext): Promise<StageRunResult> {
+    if (!(await this.isReady(ctx))) {
+      const draftPath = getUltraplanAuthoringDraftAuthoredJsonPath(
+        ctx.paths, ctx.cwd, ctx.sessionId, this.input.iteration,
+      );
+      const findingsPath = getUltraplanAuthoringDraftFindingsPath(
+        ctx.paths, ctx.cwd, ctx.sessionId, this.input.iteration,
+      );
+      const missingDraft = !fs.existsSync(draftPath);
+      return {
+        status: "failed",
+        stage: this.stage,
+        artifactPaths: [],
+        error: missingDraft
+          ? `APPROVE requires a draft authored.json at iteration ${this.input.iteration}; run the synthesize stage first.`
+          : `APPROVE requires findings.json at iteration ${this.input.iteration}; run the review stage first.`,
+      };
+    }
+
+    if (await this.isComplete(ctx)) {
+      return {
+        status: "skipped",
+        stage: this.stage,
+        artifactPaths: [ULTRAPLAN_AUTHORED_JSON_FILENAME, ULTRAPLAN_AUTHORED_MARKDOWN_FILENAME],
+        details: { reason: "canonical authored.json already exists and authoring block is cleared" },
+      };
+    }
+
+    // Step 1: load and validate the draft authored.json.
+    const draftResult = loadDraftAuthoredJson(
+      ctx.paths, ctx.cwd, ctx.sessionId, this.input.iteration,
+    );
+    if (!draftResult.ok) {
+      return {
+        status: "blocked",
+        stage: this.stage,
+        artifactPaths: [],
+        error: `APPROVE could not read draft authored.json at iteration ${this.input.iteration}: ${draftResult.error.message}`,
+      };
+    }
+
+    const validation = validateUltraPlanAuthoredArtifact(draftResult.value);
+    if (!validation.ok) {
+      const detail = validation.errors.slice(0, 3).join("; ");
+      return {
+        status: "blocked",
+        stage: this.stage,
+        artifactPaths: [],
+        error: `APPROVE draft authored.json failed schema validation: ${detail}`,
+      };
+    }
+
+    const authored: UltraPlanAuthoredArtifact = validation.value;
+
+    // Step 2: load the existing manifest, drop the `authoring` block, set state to "ready".
+    const manifestResult = loadUltraPlanManifest(ctx.paths, ctx.cwd, ctx.sessionId);
+    if (!manifestResult.ok) {
+      return {
+        status: "blocked",
+        stage: this.stage,
+        artifactPaths: [],
+        error: `APPROVE could not read the session manifest: ${manifestResult.error.message}`,
+      };
+    }
+
+    const { authoring: _authBlock, ...baseManifest } = manifestResult.value;
+    void _authBlock;
+    const canonicalManifest = {
+      ...baseManifest,
+      state: "ready" as const,
+      updatedAt: nowIso(ctx),
+    };
+
+    // Step 3: persist authored.json + manifest.json + index.json atomically.
+    const persistResult = persistAuthoredUltraPlanSession({
+      paths: ctx.paths,
+      cwd: ctx.cwd,
+      authored,
+      manifest: canonicalManifest,
+    });
+
+    if (!persistResult.ok) {
+      const kind = persistResult.error.kind;
+      // session-id-exists is only reachable if a previous run partially succeeded and left
+      // a stale index entry with a valid manifest; treat it as a recoverable block.
+      return {
+        status: "blocked",
+        stage: this.stage,
+        artifactPaths: [],
+        error: `APPROVE failed to persist canonical artifacts (${kind}): session may already be promoted or the index is corrupt.`,
+      };
+    }
+
+    // Step 4: write authored.md (best-effort — the canonical JSON is already committed).
+    const markdownPath = getUltraplanAuthoredMarkdownPath(ctx.paths, ctx.cwd, ctx.sessionId);
+    const markdown = renderApprovedMarkdown(authored);
+    try {
+      fs.mkdirSync(path.dirname(markdownPath), { recursive: true });
+      fs.writeFileSync(markdownPath, markdown, "utf8");
+    } catch {
+      // Non-critical: authored.json is already persisted; md failure is cosmetic.
+    }
+
+    // Step 5: append a pipeline-log entry summarising the promotion.
+    appendPipelineLog(ctx.paths, ctx.cwd, ctx.sessionId, {
+      recordedAt: nowIso(ctx),
+      stage: this.stage,
+      stageStatus: toManifestStageStatus("completed"),
+      iteration: this.input.iteration,
+      summary: `approved iteration ${this.input.iteration} to ${ctx.sessionId}`,
+      details: {
+        authoredPath: persistResult.authoredPath,
+        manifestPath: persistResult.manifestPath,
+        indexPath: persistResult.indexPath,
+      },
+    });
+
+    return {
+      status: "completed",
+      stage: this.stage,
+      artifactPaths: [ULTRAPLAN_AUTHORED_JSON_FILENAME, ULTRAPLAN_AUTHORED_MARKDOWN_FILENAME],
+      details: { iteration: this.input.iteration },
+    };
+  }
+}

package/src/ultraplan/authoring/stages/discover.ts

@@ -0,0 +1,289 @@
+/**
+ * DISCOVER stage runner.
+ *
+ * Spawns a single `createAgentSession` running the `discoverer` slot agent. The agent reads the
+ * intake + scout artifacts, then calls `ultraplan_decision_record` for each gray-area question
+ * that needs a locked answer before synthesis, and optionally `ultraplan_defer_idea` for items
+ * that are out of scope for this session.
+ *
+ * Resume semantics: skipped when decisions.jsonl exists with at least one line.
+ *
+ * The stage returns `awaiting-user` (not `completed`): the discover stage gate is a user review
+ * step. The pipeline driver (Phase 9) flips the stage to done on user approval.
+ *
+ * On success the stage also persists `authoring/discuss.md` rendered from all decision records.
+ */
+
+import * as fs from "node:fs";
+
+import { resolveAuthoringSlot } from "../agent-catalog.js";
+import { resolveAuthoringSlotModel } from "../model.js";
+import { modelRegistry } from "../../../config/model-registry-instance.js";
+import {
+  appendPipelineLog,
+  loadIntakeArtifact,
+  loadScoutArtifact,
+  saveAuthoringState,
+  saveDiscussArtifact,
+} from "../storage.js";
+import {
+  buildAgentDisplayName,
+  nowIso,
+  toManifestStageStatus,
+  type StageRunResult,
+  type StageRunner,
+  type StageRunnerContext,
+} from "../stage-runner.js";
+import {
+  getUltraplanAuthoringDecisionsPath,
+  getUltraplanAuthoringIntakePath,
+  getUltraplanAuthoringScoutPath,
+} from "../../project-paths.js";
+
+// ---------------------------------------------------------------------------
+// Decision record shape (as written by ultraplan_decision_record).
+// ---------------------------------------------------------------------------
+
+interface DecisionRecord {
+  sessionId?: string;
+  area: string;
+  question: string;
+  decision: string;
+  rationale?: string;
+  impact?: string[];
+  recordedAt?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function readDecisionLines(decisionsPath: string): DecisionRecord[] {
+  if (!fs.existsSync(decisionsPath)) return [];
+  const raw = fs.readFileSync(decisionsPath, "utf8");
+  const records: DecisionRecord[] = [];
+  for (const line of raw.split("\n").filter((l) => l.trim().length > 0)) {
+    try {
+      records.push(JSON.parse(line) as DecisionRecord);
+    } catch {
+      // Skip malformed lines; the stage only needs at least one to proceed.
+    }
+  }
+  return records;
+}
+
+function renderDiscussMarkdown(decisions: DecisionRecord[]): string {
+  if (decisions.length === 0) return "# Decisions\n\n(none)\n";
+  const sections = decisions.map((d) => {
+    const lines: string[] = [
+      `## ${d.area}`,
+      ``,
+      `Q: ${d.question}`,
+      `A: ${d.decision}`,
+    ];
+    if (d.rationale) {
+      lines.push(``, `Rationale: ${d.rationale}`);
+    }
+    if (d.impact && d.impact.length > 0) {
+      lines.push(``, `Impact: ${d.impact.join(", ")}`);
+    }
+    lines.push(``);
+    return lines.join("\n");
+  });
+  return `# Decisions\n\n${sections.join("\n")}`;
+}
+
+function buildDiscoverAssignment(
+  ctx: StageRunnerContext,
+  intake: unknown,
+  scout: unknown,
+): string {
+  return [
+    `# UltraPlan authoring · discover`,
+    ``,
+    `Session id: ${ctx.sessionId}`,
+    `cwd: ${ctx.cwd}`,
+    ``,
+    `## Intake artifact (verbatim)`,
+    "```json",
+    JSON.stringify(intake, null, 2),
+    "```",
+    ``,
+    `## Scout artifact (verbatim)`,
+    "```json",
+    JSON.stringify(scout, null, 2),
+    "```",
+    ``,
+    `## Your task`,
+    `Identify every gray area — ambiguous, underspecified, or high-risk decision — that must be`,
+    `locked before the synthesis stage can produce a coherent plan. For each gray area, call`,
+    `\`ultraplan_decision_record\` with sessionId=${JSON.stringify(ctx.sessionId)} and these fields:`,
+    `- area: short label (e.g. 'auth-strategy')`,
+    `- question: the exact question that needs a locked answer`,
+    `- decision: the locked answer you are recommending`,
+    `- rationale: why you chose this answer (optional but strongly recommended)`,
+    `- impact: list of domains/scenarios this affects (optional)`,
+    ``,
+    `For any idea that is clearly out of scope for this session, call \`ultraplan_defer_idea\` with`,
+    `sessionId=${JSON.stringify(ctx.sessionId)}, idea, and reason.`,
+    ``,
+    `Call \`ultraplan_decision_record\` at least once. Return after all tool calls.`,
+  ].join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Stage runner
+// ---------------------------------------------------------------------------
+
+export class DiscoverStage implements StageRunner {
+  readonly stage = "discover" as const;
+
+  async isReady(ctx: StageRunnerContext): Promise<boolean> {
+    return (
+      fs.existsSync(getUltraplanAuthoringIntakePath(ctx.paths, ctx.cwd, ctx.sessionId)) &&
+      fs.existsSync(getUltraplanAuthoringScoutPath(ctx.paths, ctx.cwd, ctx.sessionId))
+    );
+  }
+
+  async isComplete(ctx: StageRunnerContext): Promise<boolean> {
+    const decisionsPath = getUltraplanAuthoringDecisionsPath(ctx.paths, ctx.cwd, ctx.sessionId);
+    if (!fs.existsSync(decisionsPath)) return false;
+    const lines = fs.readFileSync(decisionsPath, "utf8").split("\n").filter((l) => l.trim().length > 0);
+    return lines.length > 0;
+  }
+
+  async run(ctx: StageRunnerContext): Promise<StageRunResult> {
+    if (!(await this.isReady(ctx))) {
+      return {
+        status: "failed",
+        stage: this.stage,
+        artifactPaths: [],
+        error: "DISCOVER requires both the intake and scout artifacts; run the intake and scout stages first.",
+      };
+    }
+
+    if (await this.isComplete(ctx)) {
+      return {
+        status: "skipped",
+        stage: this.stage,
+        artifactPaths: ["authoring/decisions.jsonl", "authoring/discuss.md"],
+        details: { reason: "decisions.jsonl already exists with at least one line" },
+      };
+    }
+
+    const intakeResult = loadIntakeArtifact(ctx.paths, ctx.cwd, ctx.sessionId);
+    if (!intakeResult.ok) {
+      return {
+        status: "failed",
+        stage: this.stage,
+        artifactPaths: [],
+        error: `DISCOVER could not read intake artifact: ${intakeResult.error.message}`,
+      };
+    }
+
+    const scoutResult = loadScoutArtifact(ctx.paths, ctx.cwd, ctx.sessionId);
+    if (!scoutResult.ok) {
+      return {
+        status: "failed",
+        stage: this.stage,
+        artifactPaths: [],
+        error: `DISCOVER could not read scout artifact: ${scoutResult.error.message}`,
+      };
+    }
+
+    const slotBinding = resolveAuthoringSlot("discoverer", ctx.paths, ctx.cwd);
+    const resolvedModel =
+      ctx.modelOverride ?? resolveAuthoringSlotModel(
+        "discoverer",
+        null,
+        ctx.modelConfig,
+        modelRegistry,
+        {
+          getModelForRole: (role) => ctx.platform.getModelForRole?.(role) ?? null,
+          getCurrentModel: () => ctx.platform.getCurrentModel?.() ?? "unknown",
+        },
+      );
+
+    saveAuthoringState(ctx.paths, ctx.cwd, ctx.sessionId, {
+      pipeline: "multi-stage",
+      stage: this.stage,
+      stageStatus: "running",
+      iteration: 1,
+      stallReentryCount: 0,
+      artifacts: { intake: "authoring/intake.json", scout: "authoring/scout.json" },
+      blocker: null,
+      startedAt: nowIso(ctx),
+      updatedAt: nowIso(ctx),
+    });
+
+    const sessionOpts: Record<string, unknown> = {
+      cwd: ctx.cwd,
+      agentDisplayName: buildAgentDisplayName(this.stage),
+      agentId: `ultraplan-authoring-${this.stage}-${ctx.sessionId}`,
+    };
+    if (resolvedModel.model) sessionOpts.model = resolvedModel.model;
+    if (resolvedModel.thinkingLevel) sessionOpts.thinkingLevel = resolvedModel.thinkingLevel;
+
+    const agentSession = await ctx.platform.createAgentSession(sessionOpts as never);
+    const assignment = [
+      slotBinding.definition.prompt.trim(),
+      "",
+      buildDiscoverAssignment(ctx, intakeResult.value, scoutResult.value),
+    ].join("\n");
+
+    try {
+      await agentSession.prompt(assignment, { expandPromptTemplates: false });
+    } finally {
+      await agentSession.dispose();
+    }
+
+    const verified = await this.isComplete(ctx);
+    if (!verified) {
+      return {
+        status: "failed",
+        stage: this.stage,
+        artifactPaths: [],
+        error:
+          "DISCOVER agent finished without persisting any decision records (ultraplan_decision_record was not called).",
+      };
+    }
+
+    // Build and persist discuss.md from the decisions.jsonl records.
+    const decisionsPath = getUltraplanAuthoringDecisionsPath(ctx.paths, ctx.cwd, ctx.sessionId);
+    const decisions = readDecisionLines(decisionsPath);
+    const markdown = renderDiscussMarkdown(decisions);
+    saveDiscussArtifact(ctx.paths, ctx.cwd, ctx.sessionId, markdown);
+
+    appendPipelineLog(ctx.paths, ctx.cwd, ctx.sessionId, {
+      recordedAt: nowIso(ctx),
+      stage: this.stage,
+      stageStatus: toManifestStageStatus("awaiting-user"),
+      iteration: 1,
+      summary: `discover stage awaiting user review (${decisions.length} decision(s) recorded)`,
+      details: { model: resolvedModel.model ?? null, decisionCount: decisions.length },
+    });
+
+    saveAuthoringState(ctx.paths, ctx.cwd, ctx.sessionId, {
+      pipeline: "multi-stage",
+      stage: this.stage,
+      stageStatus: "awaiting-user",
+      iteration: 1,
+      stallReentryCount: 0,
+      artifacts: {
+        intake: "authoring/intake.json",
+        scout: "authoring/scout.json",
+        discuss: "authoring/discuss.md",
+      },
+      blocker: null,
+      startedAt: nowIso(ctx),
+      updatedAt: nowIso(ctx),
+    });
+
+    return {
+      status: "awaiting-user",
+      stage: this.stage,
+      artifactPaths: ["authoring/decisions.jsonl", "authoring/discuss.md"],
+      details: { model: resolvedModel.model ?? null, decisionCount: decisions.length },
+    };
+  }
+}