supipowers 1.5.2 → 2.0.0

package/src/ultraplan/presenter.ts

@@ -0,0 +1,359 @@
+import type {
+  UltraPlanAuthoringPipelineEvent,
+  UltraPlanAuthoringStage,
+  UltraPlanAuthoringState,
+  UltraPlanAuthoredArtifact,
+  UltraPlanBlocker,
+  UltraPlanSessionSummary,
+  UltraPlanStack,
+} from "../types.js";
+import type { UltraPlanRunOutcome } from "./execution/session-runner.js";
+import type { UltraPlanSessionRecommendation } from "./next-router.js";
+import {
+  isDraftReadyToPersist,
+  type UltraPlanAuthoredDraft,
+} from "./authoring-draft.js";
+import {
+  getUltraPlanIdleReasonLabel,
+  resolveUltraPlanSessionBucket,
+  type UltraPlanResolvedCursor,
+  type UltraPlanVisibleSession,
+} from "./session-selection.js";
+
+export interface UltraPlanPickerOption {
+  value: string;
+  label: string;
+  description: string;
+}
+
+export function buildUltraPlanPickerOptions(
+  sessions: UltraPlanVisibleSession[],
+  recommendations?: ReadonlyMap<string, UltraPlanSessionRecommendation>,
+): UltraPlanPickerOption[] {
+  return sessions.map((session) => ({
+    value: session.sessionId,
+    label: `[${session.bucket}] ${formatInlineSessionTitle(session.title)}`,
+    description: describePickerDescription(session, recommendations?.get(session.sessionId)),
+  }));
+}
+
+function formatInlineSessionTitle(title: string): string {
+  return title
+    .replace(/[\u0000-\u001F\u007F]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function describePickerDescription(
+  session: UltraPlanVisibleSession,
+  recommendation?: UltraPlanSessionRecommendation,
+): string {
+  const base = describePickerSession(session);
+  if (!recommendation) return base;
+  return `${describePickerRecommendation(recommendation)} — ${base}`;
+}
+
+function describePickerSession(session: UltraPlanVisibleSession): string {
+  if (isSlice2SurfacedBlocker(session.blocker)) {
+    const idle = session.idleReasonLabel ?? `Blocked: ${session.blocker.message}`;
+    return `${idle} — ${session.blocker.code} (${session.blocker.recoveryMode})`;
+  }
+  if (session.idleReasonLabel) return `Idle: ${session.idleReasonLabel}`;
+  return `Current: ${session.cursor?.summary ?? "No active cursor"}`;
+}
+
+export function renderUltraPlanRecommendationSummary(
+  recommendation: UltraPlanSessionRecommendation,
+): string {
+  return `Recommended next: ${formatInlineSessionTitle(recommendation.session.title)} — ${describeRecommendationSummary(recommendation)}`;
+}
+
+export function renderUltraPlanRecommendationStatusLine(
+  recommendation: UltraPlanSessionRecommendation,
+): string {
+  return `Ultraplan next: ${formatInlineSessionTitle(recommendation.session.title)} — ${describeRecommendationStatus(recommendation)}`;
+}
+
+function describePickerRecommendation(
+  recommendation: UltraPlanSessionRecommendation,
+): string {
+  switch (recommendation.reasonCode) {
+    case "ongoing":
+      return "Recommended next to run";
+    case "pending":
+      return "Ready to run";
+    case "awaiting-user":
+    case "mismatch":
+      return "Inspect before running";
+    case "blocked-manual":
+      return "Action needed";
+    case "blocked":
+      return "Blocked";
+  }
+}
+
+function describeRecommendationSummary(
+  recommendation: UltraPlanSessionRecommendation,
+): string {
+  switch (recommendation.reasonCode) {
+    case "ongoing":
+      return "resume the in-progress session.";
+    case "pending":
+      return "ready to run.";
+    case "awaiting-user":
+      return "inspect it first; user input is required.";
+    case "blocked-manual":
+      return "action needed before it can resume.";
+    case "blocked":
+      return "inspect it first; it is blocked.";
+    case "mismatch":
+      return "inspect it first; session state is inconsistent.";
+  }
+}
+
+function describeRecommendationStatus(
+  recommendation: UltraPlanSessionRecommendation,
+): string {
+  switch (recommendation.reasonCode) {
+    case "ongoing":
+      return "resume now";
+    case "pending":
+      return "ready to run";
+    case "awaiting-user":
+      return "waiting for user input";
+    case "blocked-manual":
+      return "action needed";
+    case "blocked":
+      return "blocked";
+    case "mismatch":
+      return "inspect session";
+  }
+}
+
+export function renderUltraPlanStatus(
+  session: UltraPlanSessionSummary,
+  authored: UltraPlanAuthoredArtifact,
+  resolved: UltraPlanResolvedCursor,
+): string {
+  const bucket = resolveUltraPlanSessionBucket(session, resolved);
+  const idleReason = getUltraPlanIdleReasonLabel(session);
+  const stackProgress = session.stacks.length > 0
+    ? session.stacks.map((stack) => `${stack.stack} ${stack.terminalDomainCount}/${stack.domainCount} domains terminal`).join("; ")
+    : "—";
+  const domainProgress = formatDomainProgress(authored, resolved);
+
+  const lines = [
+    `Title: ${session.title}`,
+    `Goal: ${authored.goal}`,
+    `State: ${session.state}`,
+    `Bucket: ${bucket}`,
+    `Current: ${resolved.cursor.summary}`,
+    `Current source: ${resolved.source}`,
+    `Last completed (persisted): ${session.lastCompleted?.summary ?? "—"}`,
+    `Stack progress (persisted): ${stackProgress}`,
+    `Domain progress: ${domainProgress}`,
+  ];
+
+  if (idleReason) {
+    lines.push(`Idle reason: ${idleReason}`);
+  }
+  if (isSlice2SurfacedBlocker(session.blocker)) {
+    lines.push(`Blocker: ${session.blocker.code}`);
+    lines.push(`Recovery: ${session.blocker.recoveryMode}`);
+    lines.push(`Next action: ${session.blocker.nextAction}`);
+  } else if (!idleReason && resolved.cursor.targetType === "session" && resolved.cursor.status === "complete") {
+    lines.push("Next action: None — session complete");
+  } else if (!idleReason) {
+    lines.push(`Next action: Resume ${resolved.cursor.summary}`);
+  }
+
+  return lines.join("\n");
+}
+
+export function renderUltraPlanRunOutcome(outcome: UltraPlanRunOutcome): string {
+  if (outcome.kind === "completed") {
+    return [
+      `Completed: ${outcome.session.title}`,
+      `Current: ${outcome.session.cursor?.summary ?? "Session complete"}`,
+    ].join("\n");
+  }
+
+  const blockerMessage = outcome.session.blocker?.message
+    ?? outcome.session.cursor?.summary
+    ?? "Paused";
+  const prefix = outcome.session.state === "awaiting-user" ? "Awaiting user" : "Paused";
+
+  return [
+    `${prefix}: ${outcome.session.title}`,
+    blockerMessage,
+  ].join("\n");
+}
+
+function formatDomainProgress(authored: UltraPlanAuthoredArtifact, resolved: UltraPlanResolvedCursor): string {
+  const stackId = resolved.cursor.stack;
+  const domainId = resolved.cursor.domainId;
+  if (!stackId || !domainId) {
+    return "—";
+  }
+
+  const stack = authored.stacks.find((candidate) => candidate.stack === stackId);
+  const domain = stack?.domains.find((candidate) => candidate.id === domainId);
+  if (!domain) {
+    return "—";
+  }
+
+  const scenarios = [...domain.unit, ...domain.integration, ...domain.e2e];
+  const terminalCount = scenarios.filter((scenario) =>
+    scenario.status === "green-proved"
+      || scenario.status === "review-passed"
+      || scenario.status === "done").length;
+
+  return `${domain.id} ${terminalCount}/${scenarios.length} scenarios terminal`;
+}
+
+const SLICE_2_SURFACED_BLOCKER_CODES: readonly string[] = [
+  "migration-unsafe",
+  "migration-conflict",
+  "interrupted-attempt",
+];
+
+/**
+ * Slice-2 migration and interrupted-attempt blockers carry recovery metadata (recoveryMode,
+ * nextAction) that the picker and status surfaces must expose. Other blockers (legacy
+ * session-level codes) continue to use the generic idle-reason path.
+ */
+function isSlice2SurfacedBlocker(blocker: UltraPlanBlocker | null): blocker is UltraPlanBlocker {
+  return blocker !== null && SLICE_2_SURFACED_BLOCKER_CODES.includes(blocker.code);
+}
+
+export function renderUltraPlanAuthoredDraft(draft: UltraPlanAuthoredDraft): string[] {
+  const lines: string[] = [
+    `Session: ${draft.title}`,
+    `Goal: ${draft.goal}`,
+  ];
+
+  for (const stack of draft.stacks) {
+    lines.push("");
+    if (stack.applicability === "not-applicable") {
+      lines.push(`## ${stack.stack} (not-applicable)`);
+      continue;
+    }
+    renderApplicableStack(lines, stack);
+  }
+
+  const readiness = isDraftReadyToPersist(draft);
+  if (!readiness.ok) {
+    lines.push("");
+    lines.push("Readiness blockers:");
+    for (const blocker of readiness.blockers) {
+      lines.push(`  - ${describeBlocker(blocker)}`);
+    }
+  }
+
+  return lines;
+}
+
+function renderApplicableStack(lines: string[], stack: UltraPlanStack): void {
+  lines.push(`## ${stack.stack} (applicable)`);
+  lines.push(`  executor: ${stack.agentSlots.executor.agentName}`);
+  lines.push(`  tester: ${stack.agentSlots.tester.agentName}`);
+  if (stack.agentSlots.domainReviewer) {
+    lines.push(`  domain reviewer: ${stack.agentSlots.domainReviewer.agentName}`);
+  }
+  if (stack.agentSlots.stackReviewer) {
+    lines.push(`  stack reviewer: ${stack.agentSlots.stackReviewer.agentName}`);
+  }
+
+  for (const domain of stack.domains) {
+    lines.push("");
+    lines.push(`  Domain: ${domain.id} — ${domain.name}`);
+    for (const level of ["unit", "integration", "e2e"] as const) {
+      const scenarios = domain[level];
+      if (scenarios.length === 0) {
+        lines.push(`    ${level}: —`);
+        continue;
+      }
+      lines.push(`    ${level}:`);
+      for (const scenario of scenarios) {
+        lines.push(`      - ${scenario.id}: ${scenario.title}`);
+      }
+    }
+  }
+}
+
+function describeBlocker(blocker: { code: string; stack?: string; domainId?: string; slot?: string }): string {
+  switch (blocker.code) {
+    case "empty-session":
+      return "No applicable stacks (edit applicability)";
+    case "empty-applicable-stack":
+      return `${blocker.stack} has no domains (edit ${blocker.stack}.domains)`;
+    case "empty-domain":
+      return `${blocker.stack}.${blocker.domainId} has no scenarios (edit ${blocker.stack}.${blocker.domainId}.scenarios)`;
+    case "missing-required-slot":
+      return `${blocker.stack} is missing required slot ${blocker.slot}`;
+    default:
+      return blocker.code;
+  }
+}
+
+/**
+ * Render the multi-stage authoring pipeline status for a session whose manifest carries an
+ * `authoring` block. Mirrors `renderUltraPlanStatus`'s line-oriented format.
+ */
+export function renderUltraPlanAuthoringStatus(
+  sessionId: string,
+  state: UltraPlanAuthoringState,
+  events: UltraPlanAuthoringPipelineEvent[] = [],
+): string {
+  const lines: string[] = [
+    `Session: ${sessionId}`,
+    `Pipeline: ${state.pipeline}`,
+    `Stage: ${state.stage}`,
+    `Status: ${state.stageStatus}`,
+    `Iteration: ${state.iteration}`,
+  ];
+  if (state.stallReentryCount > 0) {
+    lines.push(`Stall re-entries: ${state.stallReentryCount}`);
+  }
+  const artifactKeys = Object.entries(state.artifacts)
+    .filter(([, v]) => v !== undefined && v !== null && (Array.isArray(v) ? v.length > 0 : true))
+    .map(([k]) => k);
+  lines.push(`Artifacts: ${artifactKeys.length === 0 ? "\u2014" : artifactKeys.join(", ")}`);
+  lines.push(`Started: ${state.startedAt}`);
+  lines.push(`Updated: ${state.updatedAt}`);
+  if (state.blocker) {
+    lines.push(`Blocker: ${state.blocker.code} \u2014 ${state.blocker.message}`);
+    lines.push(`Recovery: ${state.blocker.recoveryMode}`);
+  }
+  lines.push(`Next action: ${describeNextAuthoringAction(state)}`);
+  if (events.length > 0) {
+    lines.push("");
+    lines.push("Recent pipeline events:");
+    for (const ev of events.slice(-5)) {
+      lines.push(`  ${ev.recordedAt} [${ev.stage}/${ev.stageStatus}] ${ev.summary || ""}`.trimEnd());
+    }
+  }
+  return lines.join("\n");
+}
+
+function describeNextAuthoringAction(state: UltraPlanAuthoringState): string {
+  if (state.blocker) return `Resolve blocker ${state.blocker.code}`;
+  if (state.stageStatus === "awaiting-user") return `Confirm ${state.stage} to advance`;
+  if (state.stageStatus === "running") return `Resume ${state.stage}`;
+  if (state.stageStatus === "blocked") return `Repair ${state.stage} blocker`;
+  const next = nextStageOf(state.stage);
+  if (!next) return "Approval pending";
+  return `Run ${next}`;
+}
+
+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;
+  }
+}

package/src/ultraplan/project-paths.ts

@@ -0,0 +1,342 @@
+import path from "node:path";
+import type { PlatformPaths } from "../platform/types.js";
+import type { UltraPlanStackId } from "../types.js";
+import { resolveRepoIdentityRootFromFs, resolveRepoRootFromFs } from "../workspace/repo-root.js";
+import { projectSlugFromRepoRoot } from "../workspace/project-slug.js";
+
+// Canonical directory name for the UltraPlan namespace under the global state root. Kept here so
+// no other UltraPlan module needs to know this token.
+const ULTRAPLANS_DIR = "ultraplans";
+
+// Canonical artifact filenames. Exported so UltraPlan command/presenter code that builds manifest
+// references does not need to inline the strings (centralization-scan guardrail from the delta
+// spec §1).
+export const ULTRAPLAN_AUTHORED_JSON_FILENAME = "authored.json";
+export const ULTRAPLAN_AUTHORED_MARKDOWN_FILENAME = "authored.md";
+export const ULTRAPLAN_MANIFEST_FILENAME = "manifest.json";
+export const ULTRAPLAN_INDEX_FILENAME = "index.json";
+export const ULTRAPLAN_EXECUTION_LOG_FILENAME = "execution-log.jsonl";
+export const ULTRAPLAN_HOOKS_LOG_FILENAME = "hooks-log.jsonl";
+export const ULTRAPLAN_RUNTIME_TRACKER_FILENAME = "runtime-tracker.json";
+export const ULTRAPLAN_MIGRATION_RECORD_FILENAME = "migration.json";
+const ULTRAPLAN_BATCH_RUNS_DIRNAME = "batch-runs";
+export const ULTRAPLAN_BATCH_RUN_FILENAME = "run.json";
+export const ULTRAPLAN_BATCH_JOURNAL_FILENAME = "journal.jsonl";
+export const ULTRAPLAN_ACTIVE_BATCH_RUN_FILENAME = "active-run.json";
+
+// Authoring pipeline filenames (multi-stage GSD-style flow). All live under <session>/authoring/.
+const ULTRAPLAN_AUTHORING_DIRNAME = "authoring";
+export const ULTRAPLAN_AUTHORING_INTAKE_FILENAME = "intake.json";
+export const ULTRAPLAN_AUTHORING_SCOUT_FILENAME = "scout.json";
+export const ULTRAPLAN_AUTHORING_DISCUSS_FILENAME = "discuss.md";
+export const ULTRAPLAN_AUTHORING_DECISIONS_FILENAME = "decisions.jsonl";
+export const ULTRAPLAN_AUTHORING_DEFERRED_IDEAS_FILENAME = "deferred-ideas.md";
+const ULTRAPLAN_AUTHORING_RESEARCH_DIRNAME = "research";
+export const ULTRAPLAN_AUTHORING_RESEARCH_SUMMARY_FILENAME = "SUMMARY.md";
+const ULTRAPLAN_AUTHORING_DRAFTS_DIRNAME = "drafts";
+export const ULTRAPLAN_AUTHORING_DRAFT_AUTHORED_JSON_FILENAME = "authored.json";
+export const ULTRAPLAN_AUTHORING_DRAFT_AUTHORED_MD_FILENAME = "authored.md";
+export const ULTRAPLAN_AUTHORING_DRAFT_PLANNER_JSON_FILENAME = "authored.planner.json";
+export const ULTRAPLAN_AUTHORING_DRAFT_MANIFEST_FILENAME = "manifest.json";
+export const ULTRAPLAN_AUTHORING_DRAFT_FINDINGS_FILENAME = "findings.json";
+export const ULTRAPLAN_AUTHORING_PIPELINE_LOG_FILENAME = "pipeline-log.jsonl";
+
+/**
+ * Resolve the active checkout root for the given cwd. Legacy repo-local helpers still target the
+ * active checkout, not the canonical UltraPlan identity root.
+ */
+function resolveCheckoutRoot(cwd: string): string {
+  return path.resolve(resolveRepoRootFromFs(cwd));
+}
+
+/**
+ * Resolve the canonical project identity root for the given cwd. Linked worktrees of one repo
+ * must converge on the same identity root so they share one UltraPlan storage location.
+ */
+function resolveProjectIdentityRoot(cwd: string): string {
+  return path.resolve(resolveRepoIdentityRootFromFs(cwd));
+}
+
+export function getUltraplanProjectName(cwd: string): string {
+  const projectName = path.basename(path.normalize(resolveProjectIdentityRoot(cwd)));
+  if (!projectName) {
+    throw new Error(`Unable to derive ultraplan project name from cwd: ${cwd}`);
+  }
+  return projectName;
+}
+
+/**
+ * Canonical UltraPlan root: `${home}/.omp/supipowers/projects/<projectSlug>/ultraplans`.
+ * Every other UltraPlan path helper composes on top of this single function.
+ */
+export function resolveUltraPlanRoot(paths: PlatformPaths, cwd: string): string {
+  const repoIdentityRoot = resolveProjectIdentityRoot(cwd);
+  const slug = projectSlugFromRepoRoot(repoIdentityRoot);
+  return paths.global("projects", slug, ULTRAPLANS_DIR);
+}
+
+/** Project-scoped directory under the global state root (parent of `ultraplans/`). */
+export function getUltraplanProjectDir(paths: PlatformPaths, cwd: string): string {
+  const repoIdentityRoot = resolveProjectIdentityRoot(cwd);
+  const slug = projectSlugFromRepoRoot(repoIdentityRoot);
+  return paths.global("projects", slug);
+}
+
+export function getUltraplansDir(paths: PlatformPaths, cwd: string): string {
+  return resolveUltraPlanRoot(paths, cwd);
+}
+
+export function getUltraplanIndexPath(paths: PlatformPaths, cwd: string): string {
+  return path.join(resolveUltraPlanRoot(paths, cwd), ULTRAPLAN_INDEX_FILENAME);
+}
+
+export function getUltraplanBatchRunsDir(paths: PlatformPaths, cwd: string): string {
+  return path.join(resolveUltraPlanRoot(paths, cwd), ULTRAPLAN_BATCH_RUNS_DIRNAME);
+}
+
+export function getUltraplanActiveBatchRunPath(paths: PlatformPaths, cwd: string): string {
+  return path.join(getUltraplanBatchRunsDir(paths, cwd), ULTRAPLAN_ACTIVE_BATCH_RUN_FILENAME);
+}
+
+export function getUltraplanBatchRunDir(paths: PlatformPaths, cwd: string, runId: string): string {
+  return path.join(getUltraplanBatchRunsDir(paths, cwd), runId);
+}
+
+export function getUltraplanBatchRunPath(paths: PlatformPaths, cwd: string, runId: string): string {
+  return path.join(getUltraplanBatchRunDir(paths, cwd, runId), ULTRAPLAN_BATCH_RUN_FILENAME);
+}
+
+export function getUltraplanBatchJournalPath(paths: PlatformPaths, cwd: string, runId: string): string {
+  return path.join(getUltraplanBatchRunDir(paths, cwd, runId), ULTRAPLAN_BATCH_JOURNAL_FILENAME);
+}
+
+export function getUltraplanSessionDir(paths: PlatformPaths, cwd: string, sessionId: string): string {
+  return path.join(resolveUltraPlanRoot(paths, cwd), sessionId);
+}
+
+export function getUltraplanManifestPath(paths: PlatformPaths, cwd: string, sessionId: string): string {
+  return path.join(getUltraplanSessionDir(paths, cwd, sessionId), ULTRAPLAN_MANIFEST_FILENAME);
+}
+
+export function getUltraplanAuthoredJsonPath(paths: PlatformPaths, cwd: string, sessionId: string): string {
+  return path.join(getUltraplanSessionDir(paths, cwd, sessionId), ULTRAPLAN_AUTHORED_JSON_FILENAME);
+}
+
+export function getUltraplanAuthoredMarkdownPath(paths: PlatformPaths, cwd: string, sessionId: string): string {
+  return path.join(getUltraplanSessionDir(paths, cwd, sessionId), ULTRAPLAN_AUTHORED_MARKDOWN_FILENAME);
+}
+
+export function getUltraplanExecutionLogPath(paths: PlatformPaths, cwd: string, sessionId: string): string {
+  return path.join(getUltraplanSessionDir(paths, cwd, sessionId), ULTRAPLAN_EXECUTION_LOG_FILENAME);
+}
+
+export function getUltraplanHooksLogPath(paths: PlatformPaths, cwd: string, sessionId: string): string {
+  return path.join(getUltraplanSessionDir(paths, cwd, sessionId), ULTRAPLAN_HOOKS_LOG_FILENAME);
+}
+
+export function getUltraplanRuntimeTrackerPath(paths: PlatformPaths, cwd: string, sessionId: string): string {
+  return path.join(getUltraplanSessionDir(paths, cwd, sessionId), ULTRAPLAN_RUNTIME_TRACKER_FILENAME);
+}
+
+export function getUltraplanMigrationRecordPath(paths: PlatformPaths, cwd: string, sessionId: string): string {
+  return path.join(getUltraplanSessionDir(paths, cwd, sessionId), ULTRAPLAN_MIGRATION_RECORD_FILENAME);
+}
+
+export function getUltraplanReviewDir(paths: PlatformPaths, cwd: string, sessionId: string): string {
+  return path.join(getUltraplanSessionDir(paths, cwd, sessionId), "review");
+}
+
+export function getUltraplanStackReviewDir(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  stack: UltraPlanStackId,
+): string {
+  return path.join(getUltraplanReviewDir(paths, cwd, sessionId), stack);
+}
+
+export function getUltraplanDomainReviewPath(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  stack: UltraPlanStackId,
+  domainId: string,
+): string {
+  return path.join(getUltraplanStackReviewDir(paths, cwd, sessionId, stack), "domains", `${domainId}.json`);
+}
+
+export function getUltraplanStackReviewPath(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  stack: UltraPlanStackId,
+): string {
+  return path.join(getUltraplanStackReviewDir(paths, cwd, sessionId, stack), "stack.json");
+}
+
+
+// ---------------------------------------------------------------------------
+// Authoring pipeline path helpers. All paths are anchored under the session dir.
+// ---------------------------------------------------------------------------
+
+export function getUltraplanAuthoringDir(paths: PlatformPaths, cwd: string, sessionId: string): string {
+  return path.join(getUltraplanSessionDir(paths, cwd, sessionId), ULTRAPLAN_AUTHORING_DIRNAME);
+}
+
+export function getUltraplanAuthoringIntakePath(paths: PlatformPaths, cwd: string, sessionId: string): string {
+  return path.join(getUltraplanAuthoringDir(paths, cwd, sessionId), ULTRAPLAN_AUTHORING_INTAKE_FILENAME);
+}
+
+export function getUltraplanAuthoringScoutPath(paths: PlatformPaths, cwd: string, sessionId: string): string {
+  return path.join(getUltraplanAuthoringDir(paths, cwd, sessionId), ULTRAPLAN_AUTHORING_SCOUT_FILENAME);
+}
+
+export function getUltraplanAuthoringDiscussPath(paths: PlatformPaths, cwd: string, sessionId: string): string {
+  return path.join(getUltraplanAuthoringDir(paths, cwd, sessionId), ULTRAPLAN_AUTHORING_DISCUSS_FILENAME);
+}
+
+export function getUltraplanAuthoringDecisionsPath(paths: PlatformPaths, cwd: string, sessionId: string): string {
+  return path.join(getUltraplanAuthoringDir(paths, cwd, sessionId), ULTRAPLAN_AUTHORING_DECISIONS_FILENAME);
+}
+
+export function getUltraplanAuthoringDeferredIdeasPath(paths: PlatformPaths, cwd: string, sessionId: string): string {
+  return path.join(getUltraplanAuthoringDir(paths, cwd, sessionId), ULTRAPLAN_AUTHORING_DEFERRED_IDEAS_FILENAME);
+}
+
+export function getUltraplanAuthoringResearchDir(paths: PlatformPaths, cwd: string, sessionId: string): string {
+  return path.join(getUltraplanAuthoringDir(paths, cwd, sessionId), ULTRAPLAN_AUTHORING_RESEARCH_DIRNAME);
+}
+
+export function getUltraplanAuthoringResearchSummaryPath(paths: PlatformPaths, cwd: string, sessionId: string): string {
+  return path.join(
+    getUltraplanAuthoringResearchDir(paths, cwd, sessionId),
+    ULTRAPLAN_AUTHORING_RESEARCH_SUMMARY_FILENAME,
+  );
+}
+
+export function getUltraplanAuthoringResearchStackPath(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  stack: UltraPlanStackId,
+): string {
+  return path.join(getUltraplanAuthoringResearchDir(paths, cwd, sessionId), `${stack}.md`);
+}
+
+export function getUltraplanAuthoringDraftsDir(paths: PlatformPaths, cwd: string, sessionId: string): string {
+  return path.join(getUltraplanAuthoringDir(paths, cwd, sessionId), ULTRAPLAN_AUTHORING_DRAFTS_DIRNAME);
+}
+
+export function getUltraplanAuthoringDraftIterationDir(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  iteration: number,
+): string {
+  if (!Number.isInteger(iteration) || iteration < 1) {
+    throw new Error(`Iteration must be a positive integer; got ${iteration}`);
+  }
+  return path.join(getUltraplanAuthoringDraftsDir(paths, cwd, sessionId), `iteration-${iteration}`);
+}
+
+export function getUltraplanAuthoringDraftAuthoredJsonPath(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  iteration: number,
+): string {
+  return path.join(
+    getUltraplanAuthoringDraftIterationDir(paths, cwd, sessionId, iteration),
+    ULTRAPLAN_AUTHORING_DRAFT_AUTHORED_JSON_FILENAME,
+  );
+}
+
+export function getUltraplanAuthoringDraftAuthoredMarkdownPath(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  iteration: number,
+): string {
+  return path.join(
+    getUltraplanAuthoringDraftIterationDir(paths, cwd, sessionId, iteration),
+    ULTRAPLAN_AUTHORING_DRAFT_AUTHORED_MD_FILENAME,
+  );
+}
+
+export function getUltraplanAuthoringDraftPlannerJsonPath(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  iteration: number,
+): string {
+  return path.join(
+    getUltraplanAuthoringDraftIterationDir(paths, cwd, sessionId, iteration),
+    ULTRAPLAN_AUTHORING_DRAFT_PLANNER_JSON_FILENAME,
+  );
+}
+
+export function getUltraplanAuthoringDraftManifestPath(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  iteration: number,
+): string {
+  return path.join(
+    getUltraplanAuthoringDraftIterationDir(paths, cwd, sessionId, iteration),
+    ULTRAPLAN_AUTHORING_DRAFT_MANIFEST_FILENAME,
+  );
+}
+
+export function getUltraplanAuthoringDraftFindingsPath(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  iteration: number,
+): string {
+  return path.join(
+    getUltraplanAuthoringDraftIterationDir(paths, cwd, sessionId, iteration),
+    ULTRAPLAN_AUTHORING_DRAFT_FINDINGS_FILENAME,
+  );
+}
+
+export function getUltraplanAuthoringPipelineLogPath(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): string {
+  return path.join(getUltraplanAuthoringDir(paths, cwd, sessionId), ULTRAPLAN_AUTHORING_PIPELINE_LOG_FILENAME);
+}
+
+/**
+ * Returns the relative artifact path for a draft's authored.json under the authoring directory,
+ * used in `StageRunResult.artifactPaths` and log entries. Centralised here so stage files
+ * never need to embed the forbidden `authored.json` filename literal.
+ */
+export function getUltraplanAuthoringDraftAuthoredRelativePath(iteration: number): string {
+  return [
+    ULTRAPLAN_AUTHORING_DIRNAME,
+    ULTRAPLAN_AUTHORING_DRAFTS_DIRNAME,
+    `iteration-${iteration}`,
+    ULTRAPLAN_AUTHORING_DRAFT_AUTHORED_JSON_FILENAME,
+  ].join("/");
+}
+
+// ---------------------------------------------------------------------------
+// Legacy (pre-Slice-2) repo-local path helpers. Only the migration engine uses these; after
+// migration runs, the legacy directory is renamed and never written to again.
+// ---------------------------------------------------------------------------
+
+const LEGACY_DOT_DIR = ".omp";
+const LEGACY_PACKAGE_DIR = "supipowers";
+
+export function getLegacyUltraplansDir(cwd: string): string {
+  return path.join(resolveCheckoutRoot(cwd), LEGACY_DOT_DIR, LEGACY_PACKAGE_DIR, ULTRAPLANS_DIR);
+}
+
+export function getLegacyUltraplanSessionDir(cwd: string, sessionId: string): string {
+  return path.join(getLegacyUltraplansDir(cwd), sessionId);
+}
+
+export function getLegacyUltraplanIndexPath(cwd: string): string {
+  return path.join(getLegacyUltraplansDir(cwd), ULTRAPLAN_INDEX_FILENAME);
+}