ralphctl 0.4.2 → 0.4.4

package/dist/{chunk-TKPTT2UG.mjs → chunk-OFILN7QL.mjs}

@@ -1,13 +1,27 @@
 #!/usr/bin/env node
+import {
+  ProviderAiSessionAdapter,
+  SignalParser,
+  buildAutoPrompt,
+  buildEvaluatorPrompt,
+  buildIdeateAutoPrompt,
+  buildIdeatePrompt,
+  buildInteractivePrompt,
+  buildRepoOnboardPrompt,
+  buildSprintFeedbackPrompt,
+  buildTaskExecutionPrompt,
+  buildTicketRefinePrompt,
+  getActiveProvider,
+  spawnInteractive
+} from "./chunk-ZLWSPLWI.mjs";
 import {
   fetchIssueFromUrl,
   formatIssueContext,
   formatTicketDisplay,
   truncate
-} from "./chunk-JOQO4HMM.mjs";
+} from "./chunk-GQ2WFKBN.mjs";
 import {
   EXIT_ERROR,
-  EXIT_INTERRUPTED,
   EXIT_NO_TASKS,
   exitWithCode
 } from "./chunk-CFUVE2BP.mjs";
@@ -15,17 +29,18 @@ import {
   getPrompt,
   getSharedDeps
 } from "./chunk-747KW2RW.mjs";
+import {
+  updateProject
+} from "./chunk-BSB4EDGR.mjs";
 import {
   assertSprintStatus,
   closeSprint,
-  getAiProvider,
   getSprint,
   resolveSprintId,
-  setAiProvider,
   withFileLock
-} from "./chunk-YCDUVPRT.mjs";
+} from "./chunk-CBMFRQ4Y.mjs";
 import {
-  emoji,
+  isTTY,
   log,
   printHeader,
   renderTable,
@@ -35,13 +50,14 @@ import {
   showSuccess,
   showWarning,
   terminalBell
-} from "./chunk-FKMKOWLA.mjs";
+} from "./chunk-XN2UIHBY.mjs";
 import {
   ensureError,
   unwrapOrThrow,
   wrapAsync
 } from "./chunk-IWXBJD2D.mjs";
 import {
+  CURRENT_ONBOARDING_VERSION,
   IdeateOutputSchema,
   ImportTasksSchema,
   RefinedRequirementsSchema,
@@ -53,12 +69,11 @@ import {
   getTasksFilePath,
   readValidatedJson,
   writeValidatedJson
-} from "./chunk-CTP2A436.mjs";
+} from "./chunk-WDMLPXOD.mjs";
 import {
   BranchPreflightError,
   DependencyCycleError,
   DomainError,
-  IOError,
   ParseError,
   ProjectNotFoundError,
   SpawnError,
@@ -67,7 +82,7 @@ import {
   StepError,
   StorageError,
   TaskNotFoundError
-} from "./chunk-57UWLHRH.mjs";
+} from "./chunk-VAZ3LJBI.mjs";
 
 // src/integration/persistence/task.ts
 async function getTasks(sprintId) {
@@ -372,7 +387,9 @@ function unwrapError(result) {
 async function executePipeline(pipeline2, initialContext) {
   let ctx = { ...initialContext };
   const stepResults = [];
+  let stepsRun = 0;
   for (const step2 of pipeline2.steps) {
+    if (stepsRun > 0 && ctx.abortSignal?.aborted) break;
     const startTime = Date.now();
     try {
       if (step2.hooks?.pre) {
@@ -425,6 +442,7 @@ async function executePipeline(pipeline2, initialContext) {
         status: "success",
         durationMs: Date.now() - startTime
       });
+      stepsRun++;
     } catch (err) {
       const error = err instanceof Error ? err : new Error(String(err));
       stepResults.push({
@@ -1359,14 +1377,16 @@ async function runScheduler(opts, ctx) {
   const itemKey = opts.itemKey ?? DEFAULT_ITEM_KEY;
   const maxConcurrency = opts.strategy.maxConcurrency ?? DEFAULT_MAX_CONCURRENCY;
   const mutexKeyFn = opts.strategy.mutexKey ?? identityMutexKey;
-  const services = opts.createServices?.() ?? defaultServices();
+  const abortSignal = ctx.abortSignal;
+  const services = opts.createServices?.({ abortSignal }) ?? defaultServices();
   const state = {
     stats: {
       completed: 0,
       failed: 0,
       requeued: 0,
       inFlight: 0,
-      pausedRepos: /* @__PURE__ */ new Set()
+      pausedRepos: /* @__PURE__ */ new Set(),
+      cancelled: false
     },
     retryNowQueue: [],
     requeueQueue: [],
@@ -1380,6 +1400,10 @@ async function runScheduler(opts, ctx) {
   let concurrencyLimit = -1;
   try {
     for (; ; ) {
+      if (abortSignal?.aborted) {
+        state.stats.cancelled = true;
+        break;
+      }
       if (state.stopRequested) break;
       if (state.terminalError) break;
       if (opts.strategy.stopWhen?.(state.stats)) break;
@@ -1419,6 +1443,11 @@ async function runScheduler(opts, ctx) {
         }
         continue;
       }
+      if (abortSignal?.aborted) {
+        state.stats.cancelled = true;
+        opts.policies.onSettle?.(item, "failed");
+        break;
+      }
       const attempt = (state.attempts.get(item) ?? 0) + 1;
       state.attempts.set(item, attempt);
       const action = opts.policies.retryPolicy(item, error, attempt);
@@ -1427,6 +1456,9 @@ async function runScheduler(opts, ctx) {
     if (state.terminalError && state.shouldDrainOnFail && state.inFlight.size > 0) {
       await Promise.allSettled(state.inFlight.values());
     }
+    if (state.stats.cancelled && state.inFlight.size > 0) {
+      await Promise.allSettled(state.inFlight.values());
+    }
   } finally {
     if (opts.disposeServices) {
       opts.disposeServices(services);
@@ -1807,7 +1839,8 @@ ${instructions}`;
         args,
         env: this.aiSession.getSpawnEnv(),
         maxRetries: options?.maxRetries,
-        resumeSessionId: options?.resumeSessionId
+        resumeSessionId: options?.resumeSessionId,
+        abortSignal: options?.abortSignal
       });
       spinner.succeed(`${this.aiSession.getProviderDisplayName()} completed: ${task.name}`);
       const ctx = { sprintId: sprint.id, taskId: task.id, projectPath: repoPath };
@@ -1944,7 +1977,8 @@ ${instructions}`;
             cwd: repoPath,
             args: ["--add-dir", sprintDir],
             env: this.aiSession.getSpawnEnv(),
-            maxTurns: options?.maxTurns
+            maxTurns: options?.maxTurns,
+            abortSignal: options?.abortSignal
           });
           spinner.succeed(`${this.aiSession.getProviderDisplayName()} completed: ${syntheticTask.name}`);
           const ctx = { sprintId: sprint.id, taskId: syntheticTask.id, projectPath: repoPath };
@@ -2139,6 +2173,10 @@ ${repoPath}`);
         case "note":
           await this.signalHandler.handleNote(signal, ctx);
           break;
+        case "check-script-discovery":
+          break;
+        case "agents-md-proposal":
+          break;
         default: {
           const _exhaustive = signal;
           void _exhaustive;
@@ -2286,7 +2324,8 @@ function executeTask(deps) {
     const result = await deps.useCase.executeOneTask(task, sprint, {
       ...deps.options,
       ...resumeSessionId ? { resumeSessionId } : {},
-      ...ctx.contractPath ? { contractPath: ctx.contractPath } : {}
+      ...ctx.contractPath ? { contractPath: ctx.contractPath } : {},
+      ...ctx.abortSignal ? { abortSignal: ctx.abortSignal } : {}
     });
     if (!result.success) {
       return Result.error(new ParseError(`Task not completed: ${result.blocked ?? "Unknown reason"}`));
@@ -2537,7 +2576,8 @@ var EvaluateTaskUseCase = class {
       result = await this.aiSession.spawnWithRetry(prompt, {
         cwd: repoPath,
         args,
-        env: this.aiSession.getSpawnEnv()
+        env: this.aiSession.getSpawnEnv(),
+        abortSignal: options?.abortSignal
       });
     } catch (err) {
       this.logger.warning(
@@ -2595,7 +2635,8 @@ var EvaluateTaskUseCase = class {
         cwd: repoPath,
         args: ["--add-dir", sprintDir],
         env: this.aiSession.getSpawnEnv(),
-        maxTurns: options?.maxTurns
+        maxTurns: options?.maxTurns,
+        abortSignal: options?.abortSignal
       });
       spinner.succeed(`Fix attempt completed: ${task.name}`);
       const signals = this.parser.parseExecutionSignals(result.output);
@@ -2714,7 +2755,8 @@ function runEvaluatorLoopStep(useCase, options) {
     const result = await useCase.execute(ctx.sprintId, ctx.taskId, {
       iterations: options.iterations,
       maxTurns: options.maxTurns,
-      fallbackModel: ctx.generatorModel ?? void 0
+      fallbackModel: ctx.generatorModel ?? void 0,
+      abortSignal: ctx.abortSignal ?? options.abortSignal
     });
     if (!result.ok) {
       return Result.error(result.error);
@@ -2763,13 +2805,15 @@ function evaluateTask(deps) {
       },
       {
         iterations: evalCfg.iterations,
-        maxTurns: deps.options.maxTurns
+        maxTurns: deps.options.maxTurns,
+        abortSignal: ctx.abortSignal
       }
     );
     const innerCtx = {
       sprintId: ctx.sprint.id,
       taskId: ctx.task.id,
-      generatorModel: ctx.generatorModel ?? null
+      generatorModel: ctx.generatorModel ?? null,
+      abortSignal: ctx.abortSignal
     };
     let stepNames = [];
     try {
@@ -2915,11 +2959,59 @@ function withStepTrace(signalBus) {
   });
 }
 
+// src/business/pipelines/execute/resolve-dirty-tree.ts
+async function resolveDirtyTree(deps) {
+  const { repoPath, options, prompt, isTTY: isTTY2, logger, external } = deps;
+  let dirty;
+  try {
+    dirty = external.hasUncommittedChanges(repoPath);
+  } catch {
+    return;
+  }
+  if (!dirty) return;
+  if (options.resetOnResume) {
+    logger.warning(`Resetting working tree to HEAD in ${repoPath}...`);
+    external.hardResetWorkingTree(repoPath);
+    logger.success(`Working tree reset in ${repoPath}`);
+    return;
+  }
+  if (options.resumeDirty) {
+    logger.info(`Resuming with existing changes in ${repoPath}`);
+    return;
+  }
+  if (isTTY2) {
+    const keepDirty = await prompt.confirm({
+      message: `Repository at ${repoPath} has uncommitted changes. Resume with existing changes?`,
+      default: true
+    });
+    if (keepDirty) {
+      logger.info(`Resuming with existing changes in ${repoPath}`);
+      return;
+    }
+    const doReset = await prompt.confirm({
+      message: "Reset to latest commit and resume?",
+      default: false
+    });
+    if (doReset) {
+      logger.warning(`Resetting working tree to HEAD in ${repoPath}...`);
+      external.hardResetWorkingTree(repoPath);
+      logger.success(`Working tree reset in ${repoPath}`);
+      return;
+    }
+    throw new StorageError("Aborted: commit, stash, or discard changes before resuming.");
+  }
+  throw new StorageError(
+    `Repository at ${repoPath} has uncommitted changes. Commit or stash them before starting.
+Hint: pass --resume-dirty to resume with the changes intact, or --reset-on-resume to discard them.`
+  );
+}
+
 // src/business/pipelines/execute.ts
 var EXIT_SUCCESS = 0;
 var EXIT_ERROR2 = 1;
 var EXIT_NO_TASKS2 = 2;
 var EXIT_ALL_BLOCKED = 3;
+var EXIT_INTERRUPTED = 130;
 var MAX_CONCURRENCY = 10;
 var MAX_BRANCH_RETRIES = 3;
 function checkPreconditionsStep(persistence, ui, logger, options) {
@@ -3093,7 +3185,7 @@ function prepareTasksStep(persistence) {
     }
   });
 }
-function ensureBranchesStep(external, persistence, logger) {
+function ensureBranchesStep(external, persistence, logger, prompt, isTTY2, options) {
   return step("ensure-branches", async (ctx) => {
     if (ctx.proceedAfterPrecondition === false || ctx.tasksEmpty) {
       const empty = {};
@@ -3128,17 +3220,14 @@ function ensureBranchesStep(external, persistence, logger) {
     }
     try {
       for (const projectPath of uniquePaths) {
-        try {
-          if (external.hasUncommittedChanges(projectPath)) {
-            return Result.error(
-              new StorageError(
-                `Repository at ${projectPath} has uncommitted changes. Commit or stash them before starting.`
-              )
-            );
-          }
-        } catch (err) {
-          if (err instanceof StorageError) return Result.error(err);
-        }
+        await resolveDirtyTree({
+          repoPath: projectPath,
+          options,
+          prompt,
+          isTTY: isTTY2(),
+          logger,
+          external
+        });
       }
       for (const projectPath of uniquePaths) {
         const currentBranch = external.getCurrentBranch(projectPath);
@@ -3210,6 +3299,7 @@ function executeTasksStep(deps, options) {
     );
     const taskSessionIds = /* @__PURE__ */ new Map();
     const failedRepos = /* @__PURE__ */ new Set();
+    const launchedTaskIds = /* @__PURE__ */ new Set();
     let firstBlockedReason = null;
     const forceSequential = options.session === true || options.step === true;
     const uniqueRepoIds = new Set(allTasks.map((t) => t.repoId));
@@ -3342,6 +3432,7 @@ function executeTasksStep(deps, options) {
           deps.signalBus.emit({ type: "rate-limit-resumed", timestamp: /* @__PURE__ */ new Date() });
         },
         onLaunch: (task) => {
+          launchedTaskIds.add(task.id);
           const resumeId = taskSessionIds.get(task.id);
           const action = resumeId ? "Resuming" : "Starting";
           deps.logger.info(`--- ${action} task ${String(task.order)}: ${task.name} ---`);
@@ -3368,9 +3459,36 @@ function executeTasksStep(deps, options) {
       failed: 0,
       requeued: 0,
       inFlight: 0,
-      pausedRepos: /* @__PURE__ */ new Set()
+      pausedRepos: /* @__PURE__ */ new Set(),
+      cancelled: false
     };
     const stats = schedResult.ok ? schedResult.value.schedulerStats ?? emptyStats : emptyStats;
+    if (stats.cancelled && launchedTaskIds.size > 0) {
+      try {
+        const currentTasks = await deps.persistence.getTasks(sprint.id);
+        const toCancel = currentTasks.filter((t) => launchedTaskIds.has(t.id) && t.status === "in_progress");
+        if (toCancel.length > 0) {
+          const updated = currentTasks.map(
+            (t) => launchedTaskIds.has(t.id) && t.status === "in_progress" ? { ...t, status: "cancelled" } : t
+          );
+          await deps.persistence.saveTasks(updated, sprint.id);
+          for (const t of toCancel) {
+            deps.signalBus.emit({
+              type: "task-finished",
+              sprintId: sprint.id,
+              taskId: t.id,
+              status: "cancelled",
+              timestamp: /* @__PURE__ */ new Date()
+            });
+          }
+          deps.logger.warning(`Cancelled ${String(toCancel.length)} in-progress task(s).`);
+        }
+      } catch (err) {
+        deps.logger.warning(
+          `Failed to flip in-progress tasks to cancelled: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
     const summary = await buildExecutionSummary({
       persistence: deps.persistence,
       sprintId: sprint.id,
@@ -3424,6 +3542,15 @@ async function buildExecutionSummary(args) {
   const remaining = await persistence.getRemainingTasks(sprintId);
   const currentTasks = await persistence.getTasks(sprintId);
   const blocked = remaining.filter((t) => isBlocked(t, currentTasks));
+  if (stats.cancelled) {
+    return {
+      completed: stats.completed,
+      remaining: remaining.length,
+      blocked: blocked.length,
+      stopReason: "cancelled",
+      exitCode: EXIT_INTERRUPTED
+    };
+  }
   if (failedRepos.size > 0) {
     logger.warning(`Repos with failed checks: ${[...failedRepos].join(", ")}`);
   }
@@ -3544,850 +3671,322 @@ function createExecuteSprintPipeline(deps, options = {}) {
     autoActivateStep(deps.persistence),
     assertActiveStep(),
     prepareTasksStep(deps.persistence),
-    ensureBranchesStep(deps.external, deps.persistence, deps.logger),
+    ensureBranchesStep(deps.external, deps.persistence, deps.logger, deps.prompt, deps.isTTY, options),
     sprintStartCheckStep(deps.external, deps.persistence, deps.logger, options),
     executeTasksStep(deps, options),
     feedbackLoopStep(deps, options)
   ]);
 }
 
-// src/integration/ai/session/session.ts
-import { spawn, spawnSync } from "child_process";
+// src/business/pipelines/steps/validate-agents-md.ts
+function validateAgentsMdStep(adapter) {
+  return step("validate-agents-md", (ctx) => {
+    const draft = ctx.agentsMdDraft;
+    if (!draft || draft.trim().length === 0) {
+      return Result.error(new ParseError("Project context file draft is empty \u2014 AI discovery produced no content."));
+    }
+    const { violations } = adapter.lintAgentsMd(draft);
+    const partial = { agentsMdViolations: violations };
+    return Result.ok(partial);
+  });
+}
 
-// src/integration/ai/session/process-manager.ts
-var GRACEFUL_SHUTDOWN_TIMEOUT_MS = 5e3;
-var FORCE_QUIT_WINDOW_MS = 5e3;
-var ProcessManager = class _ProcessManager {
-  static instance = null;
-  /** All active AI child processes */
-  children = /* @__PURE__ */ new Set();
-  /** Cleanup callbacks (for stopping spinners, removing temp files) */
-  cleanupCallbacks = /* @__PURE__ */ new Set();
-  /** Whether we're currently shutting down */
-  exiting = false;
-  /** Whether signal handlers have been installed */
-  handlersInstalled = false;
-  /** Timestamp of first SIGINT (for double-signal detection) */
-  firstSigintAt = null;
-  /** Stored signal handler references for cleanup */
-  sigintHandler = null;
-  sigtermHandler = null;
-  constructor() {
-  }
-  /**
-   * Get the singleton instance.
-   */
-  static getInstance() {
-    _ProcessManager.instance ??= new _ProcessManager();
-    return _ProcessManager.instance;
-  }
-  /**
-   * Reset the singleton for testing.
-   * @internal
-   */
-  static resetForTesting() {
-    if (_ProcessManager.instance) {
-      _ProcessManager.instance.dispose();
-      _ProcessManager.instance = null;
-    }
-  }
-  /**
-   * Register a child process for tracking.
-   * Automatically installs signal handlers on first registration.
-   * Throws an error if called during shutdown.
-   *
-   * @throws Error if called during shutdown
-   */
-  registerChild(child) {
-    if (this.exiting) {
-      throw new Error("Cannot register child process during shutdown");
-    }
-    this.children.add(child);
-    child.once("close", () => {
-      this.children.delete(child);
-    });
-    if (!this.handlersInstalled) {
-      this.installSignalHandlers();
-      this.handlersInstalled = true;
-    }
-  }
-  /**
-   * Eagerly install signal handlers without requiring a child registration.
-   * Call this at the top of execution loops so Ctrl+C works even before
-   * the first AI process is spawned (e.g. while the spinner is visible).
-   * Idempotent — safe to call multiple times.
-   */
-  ensureHandlers() {
-    if (!this.handlersInstalled) {
-      this.installSignalHandlers();
-      this.handlersInstalled = true;
-    }
-  }
-  /**
-   * Check if a shutdown is in progress.
-   * Used by execution loops to break immediately on Ctrl+C.
-   */
-  isShuttingDown() {
-    return this.exiting;
-  }
-  /**
-   * Manually unregister a child process.
-   * Normally not needed - children auto-unregister via event listeners.
-   */
-  unregisterChild(child) {
-    this.children.delete(child);
-  }
-  /**
-   * Register a cleanup callback (for spinners, temp files, etc.).
-   * Returns a deregister function.
-   */
-  registerCleanup(callback) {
-    this.cleanupCallbacks.add(callback);
-    return () => {
-      this.cleanupCallbacks.delete(callback);
-    };
-  }
-  /**
-   * Kill all tracked child processes with the given signal.
-   * Catches errors (ESRCH = already dead, EPERM = permission denied).
-   */
-  killAll(signal) {
-    for (const child of this.children) {
-      try {
-        child.kill(signal);
-      } catch (err) {
-        const error = err;
-        if (error.code === "ESRCH") {
-          this.children.delete(child);
-        } else if (error.code === "EPERM") {
-          log.warn(`Permission denied killing process ${String(child.pid)}`);
-        } else {
-          log.error(`Error killing process ${String(child.pid)}: ${error.message}`);
-        }
-      }
-    }
-  }
-  /**
-   * Graceful shutdown sequence:
-   * 1. Run all cleanup callbacks (stop spinners)
-   * 2. Send SIGINT to all children (what AI CLI processes expect)
-   * 3. Wait up to 5 seconds for children to exit
-   * 4. Send SIGKILL to any remaining children (force)
-   * 5. Exit with code 130 (SIGINT) or 1 (force-quit)
-   *
-   * Double Ctrl+C: immediate SIGKILL + exit(1)
-   */
-  async shutdown(signal) {
-    if (signal === "SIGINT" && this.firstSigintAt) {
-      const now = Date.now();
-      if (now - this.firstSigintAt < FORCE_QUIT_WINDOW_MS) {
-        log.warn("\n\nForce quit (double signal) \u2014 killing all processes immediately...");
-        this.killAll("SIGKILL");
-        process.exit(1);
-        return;
+// src/business/pipelines/onboard.ts
+function providerInstructionsFileName(provider) {
+  if (provider === "claude") return "CLAUDE.md";
+  return ".github/copilot-instructions.md";
+}
+function loadProjectStep(deps) {
+  return step("load-project", async (ctx) => {
+    try {
+      const project = await deps.persistence.getProject(ctx.projectName);
+      const config = await deps.persistence.getConfig();
+      if (!config.aiProvider) {
+        return Result.error(
+          new ParseError(
+            "No AI provider configured \u2014 run `ralphctl config set provider <claude|copilot>` before onboarding."
+          )
+        );
       }
+      const partial = { project, provider: config.aiProvider };
+      return Result.ok(partial);
+    } catch (err) {
+      if (err instanceof ProjectNotFoundError) return Result.error(err);
+      return Result.error(new ParseError(err instanceof Error ? err.message : String(err)));
     }
-    if (this.exiting) {
-      return;
-    }
-    this.exiting = true;
-    if (signal === "SIGINT") {
-      this.firstSigintAt = Date.now();
-    }
-    log.dim("\n\nShutting down gracefully... (press Ctrl+C again to force-quit)");
-    for (const callback of this.cleanupCallbacks) {
-      try {
-        callback();
-      } catch (err) {
-        log.error(`Error in cleanup callback: ${err instanceof Error ? err.message : String(err)}`);
+  });
+}
+function selectRepoStep(deps, options) {
+  return step("select-repo", async (ctx) => {
+    const project = ctx.project;
+    if (!project) return Result.error(new ParseError("Project not loaded."));
+    const repos = project.repositories;
+    if (repos.length === 0) return Result.error(new ParseError("Project has no repositories."));
+    if (options.repo) {
+      const match = repos.find((r) => r.name === options.repo);
+      if (!match) {
+        return Result.error(new ParseError(`No repository named "${options.repo}" in project "${project.name}".`));
       }
+      return Result.ok({ repo: match });
     }
-    this.cleanupCallbacks.clear();
-    this.killAll("SIGINT");
-    const waitStart = Date.now();
-    while (this.children.size > 0 && Date.now() - waitStart < GRACEFUL_SHUTDOWN_TIMEOUT_MS) {
-      await new Promise((resolve) => setTimeout(resolve, 100));
+    if (repos.length === 1) {
+      const only = repos[0];
+      if (!only) return Result.error(new ParseError("Project has no repositories."));
+      return Result.ok({ repo: only });
     }
-    if (this.children.size > 0) {
-      log.warn(`Force-killing ${String(this.children.size)} remaining process(es)...`);
-      this.killAll("SIGKILL");
+    if (options.auto) {
+      const first = repos[0];
+      if (!first) return Result.error(new ParseError("Project has no repositories."));
+      return Result.ok({ repo: first });
     }
-    process.exit(signal === "SIGINT" ? EXIT_INTERRUPTED : 1);
-  }
-  /**
-   * Clean up all resources (for testing).
-   * @internal
-   */
-  dispose() {
-    if (this.sigintHandler) {
-      process.removeListener("SIGINT", this.sigintHandler);
-      this.sigintHandler = null;
-    }
-    if (this.sigtermHandler) {
-      process.removeListener("SIGTERM", this.sigtermHandler);
-      this.sigtermHandler = null;
+    const choice = await deps.prompt.select({
+      message: `Select a repository to onboard in "${project.name}":`,
+      choices: repos.map((r) => ({ label: `${r.name} \u2014 ${r.path}`, value: r.id }))
+    });
+    const selected = repos.find((r) => r.id === choice);
+    if (!selected) return Result.error(new ParseError("Invalid repository selection."));
+    return Result.ok({ repo: selected });
+  });
+}
+function repoPreflightStep(deps) {
+  return step("repo-preflight", (ctx) => {
+    const repo = ctx.repo;
+    const provider = ctx.provider;
+    if (!repo) return Result.error(new ParseError("Repository not resolved."));
+    if (!provider) return Result.error(new ParseError("AI provider not resolved."));
+    const validation = deps.adapter.validateRepoPath(repo.path);
+    if (!validation.exists) {
+      return Result.error(new ParseError(`Repository path does not exist or is not a directory: ${repo.path}`));
+    }
+    if (!validation.isGitRepo) {
+      return Result.error(new ParseError(`Repository is not a git repository: ${repo.path}`));
+    }
+    const existing = deps.adapter.readExistingInstructions(repo.path, provider);
+    let mode;
+    if (existing.content === null) {
+      mode = "bootstrap";
+    } else if (repo.onboardingVersion != null) {
+      mode = "update";
+    } else {
+      mode = "adopt";
     }
-    this.children.clear();
-    this.cleanupCallbacks.clear();
-    this.exiting = false;
-    this.handlersInstalled = false;
-    this.firstSigintAt = null;
-  }
-  /**
-   * Install signal handlers for SIGINT and SIGTERM.
-   * Uses process.on() (persistent) not process.once() (one-shot).
-   * Stores handler references so dispose() can remove them.
-   */
-  installSignalHandlers() {
-    this.sigintHandler = () => {
-      void this.shutdown("SIGINT");
-    };
-    this.sigtermHandler = () => {
-      void this.shutdown("SIGTERM");
-    };
-    process.on("SIGINT", this.sigintHandler);
-    process.on("SIGTERM", this.sigtermHandler);
-  }
-};
-var processLifecycleAdapter = {
-  ensureHandlers: () => {
-    ProcessManager.getInstance().ensureHandlers();
-  },
-  isShuttingDown: () => ProcessManager.getInstance().isShuttingDown()
-};
-
-// src/integration/ai/providers/claude.ts
-import { Result as Result2 } from "typescript-result";
-var claudeAdapter = {
-  name: "claude",
-  displayName: "Claude",
-  binary: "claude",
-  baseArgs: ["--permission-mode", "acceptEdits", "--effort", "xhigh"],
-  experimental: false,
-  buildInteractiveArgs(prompt, extraArgs = []) {
-    return [...this.baseArgs, ...extraArgs, "--", prompt];
-  },
-  buildHeadlessArgs(extraArgs = []) {
-    return ["-p", "--output-format", "json", ...this.baseArgs, ...extraArgs];
-  },
-  parseJsonOutput(stdout) {
-    const jsonResult = Result2.try(() => JSON.parse(stdout));
-    if (!jsonResult.ok) {
-      return { result: stdout, sessionId: null, model: null };
-    }
-    const parsed = jsonResult.value;
-    return {
-      result: parsed.result ?? stdout,
-      sessionId: parsed.session_id ?? null,
-      model: parsed.model ?? null
+    const partial = {
+      mode,
+      existingAgentsMd: existing.content
     };
-  },
-  buildResumeArgs(sessionId) {
-    if (!/^[a-zA-Z0-9_][a-zA-Z0-9_-]{0,127}$/.test(sessionId)) {
-      throw new Error("Invalid session ID format");
-    }
-    return ["--resume", sessionId];
-  },
-  detectRateLimit(stderr) {
-    const patterns = [/rate.?limit/i, /\b429\b/, /too many requests/i, /overloaded/i, /\b529\b/];
-    const isRateLimited = patterns.some((p) => p.test(stderr));
-    if (!isRateLimited) {
-      return { rateLimited: false, retryAfterMs: null };
-    }
-    const retryMatch = /retry.?after:?\s*(\d+)/i.exec(stderr);
-    const retryAfterMs = retryMatch?.[1] ? parseInt(retryMatch[1], 10) * 1e3 : null;
-    return { rateLimited: true, retryAfterMs };
-  },
-  getSpawnEnv() {
-    return { CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD: "1" };
-  }
-};
-
-// src/integration/ai/providers/copilot.ts
-import { lstat, readdir, unlink } from "fs/promises";
-import { join as join2 } from "path";
-import { Result as Result3 } from "typescript-result";
-var copilotAdapter = {
-  name: "copilot",
-  displayName: "Copilot",
-  binary: "copilot",
-  experimental: true,
-  baseArgs: ["--allow-all-tools"],
-  buildInteractiveArgs(prompt, extraArgs = []) {
-    return [...this.baseArgs, ...extraArgs, "-i", prompt];
-  },
-  buildHeadlessArgs(extraArgs = []) {
-    return ["-p", "--output-format", "json", "--autopilot", "--no-ask-user", "--share", ...this.baseArgs, ...extraArgs];
-  },
-  parseJsonOutput(stdout) {
-    const lines = stdout.trim().split("\n").filter(Boolean);
-    if (lines.length === 0) {
-      return { result: "", sessionId: null, model: null };
-    }
-    const lastLine = lines.at(-1) ?? "";
-    const jsonResult = Result3.try(() => JSON.parse(lastLine));
-    if (jsonResult.ok) {
-      const parsed = jsonResult.value;
-      return {
-        result: parsed.result ?? parsed.result_text ?? lastLine,
-        sessionId: parsed.session_id ?? null,
-        model: null
-      };
-    }
-    return { result: stdout.trim(), sessionId: null, model: null };
-  },
-  buildResumeArgs(sessionId) {
-    if (!/^[a-zA-Z0-9_][a-zA-Z0-9_-]{0,127}$/.test(sessionId)) {
-      throw new Error("Invalid session ID format");
-    }
-    return [`--resume=${sessionId}`];
-  },
-  async extractSessionId(cwd) {
-    const filesResult = await wrapAsync(
-      () => readdir(cwd),
-      (err) => new IOError(`Failed to read directory: ${cwd}`, err instanceof Error ? err : void 0)
-    );
-    if (!filesResult.ok) return null;
-    const files = filesResult.value;
-    const shareFile = files.find((f) => /^copilot-session-[a-zA-Z0-9_][a-zA-Z0-9_-]*\.md$/.test(f));
-    if (!shareFile) return null;
-    const match = /^copilot-session-([a-zA-Z0-9_][a-zA-Z0-9_-]{0,127})\.md$/.exec(shareFile);
-    if (!match?.[1]) return null;
-    const filePath = join2(cwd, shareFile);
-    const stat = await lstat(filePath).catch(() => null);
-    if (stat?.isFile()) {
-      await unlink(filePath).catch(() => {
-      });
-    }
-    return match[1];
-  },
-  detectRateLimit(stderr) {
-    const patterns = [/rate.?limit/i, /\b429\b/, /too many requests/i, /overloaded/i, /\b529\b/];
-    const isRateLimited = patterns.some((p) => p.test(stderr));
-    if (!isRateLimited) {
-      return { rateLimited: false, retryAfterMs: null };
-    }
-    const retryMatch = /retry.?after:?\s*(\d+)/i.exec(stderr);
-    const retryAfterMs = retryMatch?.[1] ? parseInt(retryMatch[1], 10) * 1e3 : null;
-    return { rateLimited: true, retryAfterMs };
-  },
-  getSpawnEnv() {
-    return {};
-  }
-};
-
-// src/integration/external/provider.ts
-async function resolveProvider() {
-  const stored = await getAiProvider();
-  if (stored) return stored;
-  const choice = await getPrompt().select({
-    message: `${emoji.donut} Which AI buddy should help with my homework?`,
-    choices: [
-      { label: "Claude Code", value: "claude" },
-      { label: "GitHub Copilot", value: "copilot" }
-    ]
+    return Result.ok(partial);
   });
-  await setAiProvider(choice);
-  return choice;
-}
-function providerDisplayName(provider) {
-  return provider === "claude" ? "Claude" : "Copilot";
-}
-
-// src/integration/ai/providers/registry.ts
-function getProvider(provider) {
-  switch (provider) {
-    case "claude":
-      return claudeAdapter;
-    case "copilot":
-      return copilotAdapter;
-  }
-}
-async function getActiveProvider() {
-  const provider = await resolveProvider();
-  return getProvider(provider);
 }
-
-// src/integration/ai/session/session.ts
-function spawnInteractive(prompt, options, provider) {
-  assertSafeCwd(options.cwd);
-  const args = prompt ? provider.buildInteractiveArgs(prompt, options.args ?? []) : [...provider.baseArgs, ...options.args ?? []];
-  const env = options.env ? { ...process.env, ...options.env } : void 0;
-  const result = spawnSync(provider.binary, args, {
-    cwd: options.cwd,
-    stdio: "inherit",
-    env
+function aiInventoryStep(deps) {
+  return step("ai-inventory", async (ctx) => {
+    const repo = ctx.repo;
+    const mode = ctx.mode;
+    const provider = ctx.provider;
+    if (!repo || !mode || !provider)
+      return Result.error(new ParseError("Preflight did not populate repo/mode/provider."));
+    deps.logger.info(`Asking AI to inventory ${repo.name}...`);
+    let result;
+    try {
+      result = await deps.adapter.discoverAgentsMd({
+        repoPath: repo.path,
+        mode,
+        existingAgentsMd: ctx.existingAgentsMd ?? null,
+        projectType: deps.adapter.inferProjectType(repo.path),
+        checkScriptSuggestion: repo.checkScript ?? "",
+        fileName: providerInstructionsFileName(provider)
+      });
+    } catch (err) {
+      return Result.error(new ParseError(`AI inventory failed: ${err instanceof Error ? err.message : String(err)}`));
+    }
+    if (!result.agentsMd) {
+      return Result.error(
+        new ParseError("AI returned no project context file proposal \u2014 try again, or edit the file manually.")
+      );
+    }
+    const partial = {
+      agentsMdDraft: result.agentsMd,
+      checkScriptDraft: result.checkScript,
+      changes: result.changes
+    };
+    return Result.ok(partial);
   });
-  if (result.error) {
-    return { code: 1, error: `Failed to spawn ${provider.binary} CLI: ${result.error.message}` };
-  }
-  return { code: result.status ?? 1 };
 }
-async function spawnHeadless(options, provider) {
-  assertSafeCwd(options.cwd);
-  const p = provider ?? await getActiveProvider();
-  return new Promise((resolve, reject) => {
-    const allArgs = p.buildHeadlessArgs(options.args ?? []);
-    if (options.resumeSessionId) {
-      try {
-        allArgs.push(...p.buildResumeArgs(options.resumeSessionId));
-      } catch {
-        reject(new SpawnError("Invalid session ID format", "", 1));
-        return;
+function retryOnViolationStep(deps) {
+  return step(
+    "retry-agents-md-on-violation",
+    async (ctx) => {
+      const violations = ctx.agentsMdViolations ?? [];
+      if (violations.length === 0) return Result.ok({});
+      const repo = ctx.repo;
+      const mode = ctx.mode;
+      const provider = ctx.provider;
+      const draft = ctx.agentsMdDraft;
+      if (!repo || !mode || !provider || !draft) {
+        return Result.error(new ParseError("Retry requires repo, mode, provider, and an existing draft."));
       }
-    }
-    const child = spawn(p.binary, allArgs, {
-      cwd: options.cwd,
-      stdio: ["pipe", "pipe", "pipe"],
-      env: options.env ? { ...process.env, ...options.env } : void 0
-    });
-    const manager = ProcessManager.getInstance();
-    try {
-      manager.registerChild(child);
-    } catch {
-      reject(new SpawnError("Cannot spawn during shutdown", "", 1));
-      return;
-    }
-    const MAX_STDOUT_SIZE = 1e7;
-    const MAX_PROMPT_SIZE = 1e6;
-    if (options.prompt) {
-      if (options.prompt.length > MAX_PROMPT_SIZE) {
-        reject(new SpawnError("Prompt exceeds maximum size (1MB)", "", 1));
-        return;
+      deps.logger.warn(
+        `Project context file draft failed ${String(violations.length)} rule(s); asking AI for a fix...`
+      );
+      const violationSummary = violations.map((v) => `- [${v.rule}] ${v.message}`).join("\n");
+      const feedbackContext = [
+        ctx.existingAgentsMd ?? "",
+        "",
+        "---",
+        "",
+        "Your previous draft (below) violated these rules:",
+        violationSummary,
+        "",
+        "Fix every violation and re-emit the full project context file plus check-script.",
+        "",
+        draft
+      ].join("\n");
+      let retry;
+      try {
+        retry = await deps.adapter.discoverAgentsMd({
+          repoPath: repo.path,
+          mode,
+          existingAgentsMd: feedbackContext,
+          projectType: deps.adapter.inferProjectType(repo.path),
+          checkScriptSuggestion: ctx.checkScriptDraft ?? repo.checkScript ?? "",
+          fileName: providerInstructionsFileName(provider)
+        });
+      } catch (err) {
+        return Result.error(new ParseError(`Retry failed: ${err instanceof Error ? err.message : String(err)}`));
       }
-      child.stdin.write(options.prompt);
-    }
-    child.stdin.end();
-    let rawStdout = "";
-    let stderr = "";
-    child.stdout.on("data", (data) => {
-      if (rawStdout.length < MAX_STDOUT_SIZE) {
-        rawStdout += data.toString();
+      if (!retry.agentsMd) {
+        deps.logger.warn("Retry produced no new proposal \u2014 keeping original draft.");
+        return Result.ok({});
       }
-    });
-    child.stderr.on("data", (data) => {
-      stderr += data.toString();
-    });
-    child.on("close", (code) => {
-      void (async () => {
-        const exitCode = code ?? 1;
-        const { result, sessionId: parsedSessionId, model: parsedModel } = p.parseJsonOutput(rawStdout);
-        const sessionId = parsedSessionId ?? await p.extractSessionId?.(options.cwd) ?? null;
-        if (exitCode !== 0) {
-          reject(
-            new SpawnError(
-              `${p.displayName} CLI exited with code ${String(exitCode)}: ${stderr}`,
-              stderr,
-              exitCode,
-              sessionId
-            )
-          );
-        } else {
-          resolve({ stdout: result, stderr, exitCode: 0, sessionId, model: parsedModel });
-        }
-      })().catch((err) => {
-        reject(new SpawnError(`Unexpected error in close handler: ${String(err)}`, "", 1));
-      });
-    });
-    child.on("error", (err) => {
-      reject(new SpawnError(`Failed to spawn ${p.binary} CLI: ${err.message}`, "", 1));
-    });
+      const { violations: retryViolations } = deps.adapter.lintAgentsMd(retry.agentsMd);
+      const partial = {
+        agentsMdDraft: retry.agentsMd,
+        checkScriptDraft: retry.checkScript ?? ctx.checkScriptDraft,
+        agentsMdViolations: retryViolations
+      };
+      return Result.ok(partial);
+    }
+  );
+}
+function checkDriftStep(deps) {
+  return step("check-drift", (ctx) => {
+    const draft = ctx.agentsMdDraft;
+    const repo = ctx.repo;
+    if (!draft || !repo) return Result.error(new ParseError("check-drift requires a draft and repo."));
+    const warnings = deps.adapter.detectCommandDrift(draft, repo.path);
+    const residual = ctx.agentsMdViolations ?? [];
+    for (const v of residual) {
+      warnings.push(`lint[${v.rule}]: ${v.message}`);
+    }
+    const alreadyCurrent = ctx.mode === "update" && warnings.length === 0 && (!ctx.changes || ctx.changes.trim().length === 0);
+    const partial = {
+      driftWarnings: warnings,
+      alreadyCurrent
+    };
+    return Result.ok(partial);
   });
 }
-var DEFAULT_MAX_RETRIES = 5;
-var BASE_DELAY_MS = 2e3;
-var MAX_DELAY_MS = 12e4;
-var DEFAULT_TOTAL_TIMEOUT_MS = 6e5;
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-function jitter() {
-  return Math.floor(Math.random() * 1e3);
-}
-async function spawnWithRetry(options, retryOptions, provider) {
-  const p = provider ?? await getActiveProvider();
-  const maxRetries = retryOptions?.maxRetries ?? DEFAULT_MAX_RETRIES;
-  const totalTimeoutMs = retryOptions?.totalTimeoutMs ?? DEFAULT_TOTAL_TIMEOUT_MS;
-  const startTime = Date.now();
-  let resumeSessionId = options.resumeSessionId;
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    const elapsed = Date.now() - startTime;
-    if (attempt > 0 && elapsed >= totalTimeoutMs) {
-      throw new SpawnError(`Total retry timeout exceeded (${String(totalTimeoutMs)}ms)`, "", 1, resumeSessionId);
-    }
-    const r = await wrapAsync(async () => spawnHeadless({ ...options, resumeSessionId }, p), ensureError);
-    if (r.ok) return r.value;
-    const err = r.error;
-    if (!(err instanceof SpawnError) || !err.rateLimited) {
-      throw err;
-    }
-    if (err.sessionId) {
-      resumeSessionId = err.sessionId;
-    }
-    if (attempt >= maxRetries) {
-      throw err;
+function reviewAndConfirmStep(deps, options) {
+  return step("review-and-confirm", async (ctx) => {
+    if (ctx.alreadyCurrent || options.auto || options.dryRun) {
+      const partial2 = {
+        agentsMdFinal: ctx.agentsMdDraft,
+        checkScriptFinal: ctx.checkScriptDraft ?? null
+      };
+      return Result.ok(partial2);
     }
-    const delay = Math.min(err.retryAfterMs ?? BASE_DELAY_MS * Math.pow(2, attempt), MAX_DELAY_MS) + jitter();
-    retryOptions?.onRetry?.(attempt + 1, delay, err);
-    await sleep(delay);
-  }
-  throw new Error("Max retries exceeded");
-}
-
-// src/integration/ui/tui/runtime/screen.ts
-var ENTER_ALT_SCREEN = "\x1B[?1049h";
-var LEAVE_ALT_SCREEN = "\x1B[?1049l";
-var HIDE_CURSOR = "\x1B[?25l";
-var SHOW_CURSOR = "\x1B[?25h";
-var CLEAR_SCREEN = "\x1B[2J\x1B[H";
-var altScreenActive = false;
-var safetyNetsInstalled = false;
-function writeRaw(seq) {
-  if (process.stdout.isTTY) process.stdout.write(seq);
-}
-function restore() {
-  if (!altScreenActive) return;
-  altScreenActive = false;
-  writeRaw(SHOW_CURSOR);
-  writeRaw(LEAVE_ALT_SCREEN);
-}
-function installSafetyNets() {
-  if (safetyNetsInstalled) return;
-  safetyNetsInstalled = true;
-  process.on("exit", restore);
-  for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
-    process.on(sig, () => {
-      restore();
-      process.kill(process.pid, sig);
+    const fileName = ctx.provider ? providerInstructionsFileName(ctx.provider) : "project context file";
+    const edited = await deps.prompt.editor({
+      message: `Review ${fileName} (save to accept, cancel to abort):`,
+      default: ctx.agentsMdDraft ?? ""
     });
-  }
-  process.on("uncaughtException", (err) => {
-    restore();
-    setImmediate(() => {
-      throw err;
+    if (edited === null) {
+      return Result.error(new ParseError("User cancelled project context file review."));
+    }
+    const checkEdited = await deps.prompt.input({
+      message: "Check script (optional; empty skips):",
+      default: ctx.checkScriptDraft ?? ""
     });
+    const finalCheck = checkEdited.trim() === "" ? null : checkEdited.trim();
+    const partial = {
+      agentsMdFinal: edited,
+      checkScriptFinal: finalCheck
+    };
+    return Result.ok(partial);
   });
 }
-function enterAltScreen() {
-  if (altScreenActive) return;
-  if (!process.stdout.isTTY) return;
-  installSafetyNets();
-  altScreenActive = true;
-  writeRaw(ENTER_ALT_SCREEN);
-  writeRaw(CLEAR_SCREEN);
-  writeRaw(HIDE_CURSOR);
-}
-function exitAltScreen() {
-  restore();
-}
-
-// src/integration/ui/tui/runtime/suspend.ts
-var activeInstance = null;
-function registerTuiInstance(instance) {
-  activeInstance = instance;
-  return () => {
-    if (activeInstance === instance) {
-      activeInstance = null;
-    }
-  };
-}
-async function withSuspendedTui(cb) {
-  const instance = activeInstance;
-  if (instance === null) {
-    return cb();
-  }
-  exitAltScreen();
-  try {
-    return await cb();
-  } finally {
-    enterAltScreen();
-    instance.clear();
-  }
-}
-
-// src/integration/ai/session/session-adapter.ts
-var ProviderAiSessionAdapter = class {
-  provider = null;
-  /** Lazily resolve and cache the active provider. */
-  async getProvider() {
-    this.provider ??= await getActiveProvider();
-    return this.provider;
-  }
-  /** Public eager resolver — required before the sync getters can be used safely. */
-  async ensureReady() {
-    await this.getProvider();
-  }
-  async spawnInteractive(prompt, options) {
-    const provider = await this.getProvider();
-    await withSuspendedTui(() => {
-      const result = spawnInteractive(
-        prompt,
-        {
-          cwd: options.cwd,
-          args: options.args,
-          env: options.env
-        },
-        provider
+function writeArtifactsStep(deps, options) {
+  return step("write-artifacts", async (ctx) => {
+    if (options.dryRun || ctx.alreadyCurrent) {
+      deps.logger.info(options.dryRun ? "Dry run \u2014 skipping writes." : "Already up to date \u2014 skipping writes.");
+      return Result.ok({});
+    }
+    const repo = ctx.repo;
+    const project = ctx.project;
+    const provider = ctx.provider;
+    const content = ctx.agentsMdFinal;
+    if (!repo || !project || !provider || !content) {
+      return Result.error(new ParseError("write-artifacts requires repo, project, provider, and final content."));
+    }
+    if (ctx.mode === "adopt") {
+      deps.logger.warn(
+        "Adopt mode \u2014 existing project context file left untouched. Review the proposed additions and apply them manually."
       );
-      if (result.error) {
-        throw new Error(result.error);
-      }
-    });
-  }
-  async spawnHeadless(prompt, options) {
-    const provider = await this.getProvider();
-    const result = await spawnHeadless(
-      {
-        cwd: options.cwd,
-        args: options.args,
-        env: options.env,
-        prompt,
-        resumeSessionId: options.resumeSessionId
-      },
-      provider
-    );
-    return {
-      output: result.stdout,
-      sessionId: result.sessionId ?? void 0,
-      model: result.model ?? void 0
-    };
-  }
-  async spawnWithRetry(prompt, options) {
-    const provider = await this.getProvider();
-    const result = await spawnWithRetry(
-      {
-        cwd: options.cwd,
-        args: options.args,
-        env: options.env,
-        prompt,
-        resumeSessionId: options.resumeSessionId
-      },
-      { maxRetries: options.maxRetries },
-      provider
-    );
-    return {
-      output: result.stdout,
-      sessionId: result.sessionId ?? void 0,
-      model: result.model ?? void 0
-    };
-  }
-  async resumeSession(sessionId, prompt, options) {
-    const provider = await this.getProvider();
-    const result = await spawnWithRetry(
-      {
-        cwd: options.cwd,
-        args: options.args,
-        env: options.env,
-        prompt,
-        resumeSessionId: sessionId
-      },
-      void 0,
-      provider
-    );
-    return {
-      output: result.stdout,
-      sessionId: result.sessionId ?? void 0,
-      model: result.model ?? void 0
-    };
-  }
-  getProviderName() {
-    if (!this.provider) {
-      throw new Error("Provider not yet resolved. Call an async method first.");
-    }
-    return this.provider.name;
-  }
-  getProviderDisplayName() {
-    if (!this.provider) {
-      throw new Error("Provider not yet resolved. Call an async method first.");
+      return Result.ok({
+        driftWarnings: [
+          ...ctx.driftWarnings ?? [],
+          "adopt-mode: authored file preserved; proposed additions not written \u2014 apply manually."
+        ]
+      });
     }
-    return this.provider.displayName;
-  }
-  getSpawnEnv() {
-    if (!this.provider) {
-      throw new Error("Provider not yet resolved. Call an async method first.");
+    try {
+      const written = deps.adapter.writeProviderInstructions(repo.path, content, provider);
+      const updatedRepos = project.repositories.map((r) => {
+        if (r.id !== repo.id) return r;
+        const next = {
+          ...r,
+          onboardingVersion: CURRENT_ONBOARDING_VERSION
+        };
+        const cs = ctx.checkScriptFinal;
+        if (cs && cs.length > 0) {
+          next.checkScript = cs;
+        } else if (cs === null) {
+          delete next.checkScript;
+        }
+        return next;
+      });
+      await deps.updateProjectRepos(project.name, updatedRepos);
+      const partial = {
+        writtenPath: written.path
+      };
+      return Result.ok(partial);
+    } catch (err) {
+      return Result.error(new ParseError(`Write failed: ${err instanceof Error ? err.message : String(err)}`));
     }
-    return this.provider.getSpawnEnv();
-  }
-};
-
-// src/integration/ai/prompts/loader.ts
-import { existsSync, readFileSync } from "fs";
-import { dirname, join as join3 } from "path";
-import { fileURLToPath } from "url";
-var __dirname = dirname(fileURLToPath(import.meta.url));
-function getPromptDir() {
-  const bundled = join3(__dirname, "prompts");
-  if (existsSync(bundled)) return bundled;
-  return __dirname;
-}
-var promptDir = getPromptDir();
-function loadTemplate(name) {
-  return readFileSync(join3(promptDir, `${name}.md`), "utf-8");
-}
-function loadPartial(name) {
-  return loadTemplate(name).replace(/\s+$/, "");
-}
-var UNREPLACED_TOKEN_RE = /\{\{[A-Z_]+\}\}/g;
-function composePrompt(template, substitutions) {
-  let result = template;
-  for (const [key, value] of Object.entries(substitutions)) {
-    result = result.replaceAll(`{{${key}}}`, value);
-  }
-  const remaining = result.match(UNREPLACED_TOKEN_RE);
-  if (remaining) {
-    throw new Error(`composePrompt: unreplaced placeholders: ${[...new Set(remaining)].join(", ")}`);
-  }
-  return result;
-}
-var CHECK_GATE_EXAMPLE = "Run the project's check gate \u2014 all pass (omit this step when the project has no check script)";
-function buildPlanCommon(projectToolingSection) {
-  return composePrompt(loadPartial("plan-common"), {
-    PLAN_COMMON_EXAMPLES: loadPartial("plan-common-examples"),
-    PROJECT_TOOLING: projectToolingSection,
-    CHECK_GATE_EXAMPLE
-  });
-}
-function buildPlannerBase(projectToolingSection) {
-  return {
-    HARNESS_CONTEXT: loadPartial("harness-context"),
-    COMMON: buildPlanCommon(projectToolingSection),
-    VALIDATION: loadPartial("validation-checklist"),
-    SIGNALS: loadPartial("signals-planning"),
-    CHECK_GATE_EXAMPLE
-  };
-}
-function buildInteractivePrompt(context, outputFile, schema, projectToolingSection) {
-  return composePrompt(loadTemplate("plan-interactive"), {
-    ...buildPlannerBase(projectToolingSection),
-    CONTEXT: context,
-    OUTPUT_FILE: outputFile,
-    SCHEMA: schema
-  });
-}
-function buildAutoPrompt(context, schema, projectToolingSection) {
-  return composePrompt(loadTemplate("plan-auto"), {
-    ...buildPlannerBase(projectToolingSection),
-    CONTEXT: context,
-    SCHEMA: schema
-  });
-}
-function buildTaskExecutionPrompt(progressFilePath, noCommit, contextFileName, projectToolingSection = "") {
-  let template = loadTemplate("task-execution");
-  if (noCommit) {
-    template = template.replace(/^[ \t]*\{\{COMMIT_STEP\}\}\n/m, "\n");
-    template = template.replace(/^[ \t]*\{\{COMMIT_CONSTRAINT\}\}\n/m, "");
-  }
-  const commitStep = noCommit ? "" : "   - **Before continuing:** Create a git commit with a descriptive message for the changes made.";
-  const commitConstraint = noCommit ? "" : "- **Must commit** \u2014 Create a git commit before signaling completion.";
-  return composePrompt(template, {
-    HARNESS_CONTEXT: loadPartial("harness-context"),
-    SIGNALS: loadPartial("signals-task"),
-    PROGRESS_FILE: progressFilePath,
-    COMMIT_STEP: commitStep,
-    COMMIT_CONSTRAINT: commitConstraint,
-    CONTEXT_FILE: contextFileName,
-    PROJECT_TOOLING: projectToolingSection
-  });
-}
-function buildTicketRefinePrompt(ticketContent, outputFile, schema, issueContext = "") {
-  const template = loadTemplate("ticket-refine");
-  const issueContextSection = issueContext ? `<context>
-
-${issueContext}
-
-</context>` : "";
-  return composePrompt(template, {
-    TICKET: ticketContent,
-    OUTPUT_FILE: outputFile,
-    SCHEMA: schema,
-    ISSUE_CONTEXT: issueContextSection
   });
 }
-function buildIdeatePrompt(ideaTitle, ideaDescription, projectName, repositories, outputFile, schema, projectToolingSection) {
-  return composePrompt(loadTemplate("ideate"), {
-    ...buildPlannerBase(projectToolingSection),
-    IDEA_TITLE: ideaTitle,
-    IDEA_DESCRIPTION: ideaDescription,
-    PROJECT_NAME: projectName,
-    REPOSITORIES: repositories,
-    OUTPUT_FILE: outputFile,
-    SCHEMA: schema
-  });
-}
-function buildIdeateAutoPrompt(ideaTitle, ideaDescription, projectName, repositories, schema, projectToolingSection) {
-  return composePrompt(loadTemplate("ideate-auto"), {
-    ...buildPlannerBase(projectToolingSection),
-    IDEA_TITLE: ideaTitle,
-    IDEA_DESCRIPTION: ideaDescription,
-    PROJECT_NAME: projectName,
-    REPOSITORIES: repositories,
-    SCHEMA: schema
-  });
-}
-function renderExtraDimensions(extras) {
-  if (extras.length === 0) {
-    return { section: "", passBar: "", assessment: "" };
-  }
-  const section = extras.map(
-    (name) => `
-<dimension name="${name}" floor="false">
-Additional task-specific dimension flagged by the planner. Apply judgment to whether the implementation satisfies this dimension given the task's verification criteria and steps.
-</dimension>
-`
-  ).join("");
-  const passBar = extras.map((name) => `
-- **${name}**: Task-specific dimension flagged by the planner`).join("");
-  return {
-    section,
-    passBar,
-    assessment: extras.map((name) => `
-**${name}**: PASS/FAIL \u2014 [one-line finding]`).join("")
-  };
-}
-function buildEvaluatorPrompt(ctx) {
-  const template = loadTemplate("task-evaluation");
-  const descriptionSection = ctx.taskDescription ? `
-**Description:** ${ctx.taskDescription}` : "";
-  const stepsSection = ctx.taskSteps.length > 0 ? `
-**Implementation Steps:**
-${ctx.taskSteps.map((s) => `- ${s}`).join("\n")}` : "";
-  const criteriaSection = ctx.verificationCriteria.length > 0 ? `
-**Verification Criteria:**
-${ctx.verificationCriteria.map((c) => `- ${c}`).join("\n")}` : "";
-  const checkSection = ctx.checkScriptSection ? `
-
-${ctx.checkScriptSection}` : "";
-  const extras = renderExtraDimensions(ctx.extraDimensions);
-  const extraAssessmentPass = extras.assessment.replace(/PASS\/FAIL/g, "PASS");
-  return composePrompt(template, {
-    HARNESS_CONTEXT: loadPartial("harness-context"),
-    SIGNALS: loadPartial("signals-evaluation"),
-    TASK_NAME: ctx.taskName,
-    TASK_DESCRIPTION_SECTION: descriptionSection,
-    TASK_STEPS_SECTION: stepsSection,
-    VERIFICATION_CRITERIA_SECTION: criteriaSection,
-    PROJECT_PATH: ctx.projectPath,
-    CHECK_SCRIPT_SECTION: checkSection,
-    PROJECT_TOOLING: ctx.projectToolingSection,
-    EXTRA_DIMENSIONS_SECTION: extras.section,
-    EXTRA_DIMENSIONS_PASS_BAR: extras.passBar,
-    EXTRA_DIMENSIONS_ASSESSMENT_PASS: extraAssessmentPass,
-    EXTRA_DIMENSIONS_ASSESSMENT_MIXED: extras.assessment
+function verifyCheckScriptStep(deps) {
+  return step("verify-check-script", (ctx) => {
+    const cmd = ctx.checkScriptFinal;
+    if (!cmd) return Result.ok({});
+    if (!/^\S/.test(cmd)) {
+      deps.logger.warn(`Check script looks malformed: ${cmd}`);
+    }
+    return Result.ok({});
   });
 }
-function buildSprintFeedbackPrompt(sprintName, completedTasks, feedback, branch) {
-  const template = loadTemplate("sprint-feedback");
-  const branchSection = branch ? `
-**Branch:** ${branch}
-` : "";
-  return composePrompt(template, {
-    HARNESS_CONTEXT: loadPartial("harness-context"),
-    SIGNALS: loadPartial("signals-task"),
-    SPRINT_NAME: sprintName,
-    BRANCH_SECTION: branchSection,
-    COMPLETED_TASKS: completedTasks,
-    FEEDBACK: feedback
-  });
+function createOnboardPipeline(deps, options = {}) {
+  return pipeline("onboard", [
+    loadProjectStep(deps),
+    selectRepoStep(deps, options),
+    repoPreflightStep(deps),
+    aiInventoryStep(deps),
+    validateAgentsMdStep(deps.adapter),
+    retryOnViolationStep(deps),
+    checkDriftStep(deps),
+    reviewAndConfirmStep(deps, options),
+    writeArtifactsStep(deps, options),
+    verifyCheckScriptStep(deps)
+  ]);
 }
 
 // src/integration/ai/prompts/prompt-builder-adapter.ts
@@ -4523,10 +4122,12 @@ async function importTasksAppend(tasks, sprintId) {
           name: taskInput.name,
           description: taskInput.description,
           steps: taskInput.steps ?? [],
+          verificationCriteria: taskInput.verificationCriteria ?? [],
           ticketId: taskInput.ticketId,
           blockedBy: [],
           // Set later
-          repoId: taskInput.repoId
+          repoId: taskInput.repoId,
+          extraDimensions: taskInput.extraDimensions
         },
         sprintId
       );
@@ -4579,7 +4180,8 @@ async function importTasksReplace(tasks, sprintId) {
       // Set in second pass
       repoId: taskInput.repoId,
       evaluated: false,
-      verified: false
+      verified: false,
+      extraDimensions: taskInput.extraDimensions
     });
   }
   for (let i = 0; i < tasks.length; i++) {
@@ -4595,8 +4197,8 @@ async function importTasksReplace(tasks, sprintId) {
 
 // src/integration/cli/commands/ticket/refine-utils.ts
 import { writeFile } from "fs/promises";
-import { join as join4 } from "path";
-import { Result as Result4 } from "typescript-result";
+import { join as join2 } from "path";
+import { Result as Result2 } from "typescript-result";
 function formatTicketForPrompt(ticket) {
   const lines = [];
   lines.push(`### ${formatTicketDisplay(ticket)}`);
@@ -4614,7 +4216,7 @@ function formatTicketForPrompt(ticket) {
 }
 function parseRequirementsFile(content) {
   const jsonStr = extractJsonArray(content);
-  const parseR = Result4.try(() => JSON.parse(jsonStr));
+  const parseR = Result2.try(() => JSON.parse(jsonStr));
   if (!parseR.ok) {
     throw new Error(`Invalid JSON: ${parseR.error.message}`, { cause: parseR.error });
   }
@@ -4634,7 +4236,7 @@ ${issues}`);
   return result.data;
 }
 async function runAiSession(workingDir, prompt, ticketTitle) {
-  const contextFile = join4(workingDir, "refine-context.md");
+  const contextFile = join2(workingDir, "refine-context.md");
   await writeFile(contextFile, prompt, "utf-8");
   const provider = await getActiveProvider();
   const startPrompt = `I need help refining the requirements for "${ticketTitle}". The full context is in refine-context.md. Please read that file now and follow the instructions to help refine the ticket requirements.`;
@@ -4652,7 +4254,7 @@ async function runAiSession(workingDir, prompt, ticketTitle) {
 }
 
 // src/integration/ai/evaluator.ts
-var DIMENSION_LINE = /\*\*([A-Za-z][A-Za-z0-9]{2,29})\*\*\s*:\s*(PASS|FAIL)\s*(?:—|-)\s*(.+)/gi;
+var DIMENSION_LINE = /\*\*([A-Za-z][A-Za-z0-9]{2,29})\*\*\s*:\s*(PASS|FAIL)(?:\s*(?:—|-)\s*([^\n]*\S))?/gi;
 function parseDimensionScores(output) {
   const scores = [];
   const seen = /* @__PURE__ */ new Set();
@@ -4661,15 +4263,16 @@ function parseDimensionScores(output) {
   while ((match = DIMENSION_LINE.exec(output)) !== null) {
     const rawName = match[1];
     const verdict = match[2];
-    const finding = match[3];
-    if (!rawName || !verdict || !finding) continue;
+    const finding = (match[3] ?? "").trim();
+    if (!rawName || !verdict) continue;
     const name = rawName.toLowerCase();
     if (seen.has(name)) continue;
     seen.add(name);
+    const hasJustification = finding.length > 0;
     scores.push({
       dimension: name,
-      passed: verdict.toUpperCase() === "PASS",
-      finding: finding.trim()
+      passed: verdict.toUpperCase() === "PASS" && hasJustification,
+      finding
     });
   }
   return scores;
@@ -4689,132 +4292,6 @@ function parseEvaluationResult(output) {
   return { passed: false, status: "malformed", output, dimensions };
 }
 
-// src/integration/signals/parser.ts
-var SIGNAL_PATTERNS = {
-  progress: /<progress>([\s\S]*?)<\/progress>/g,
-  progressWithFiles: /<progress>([\s\S]*?)<\/progress>/,
-  evaluation_passed: /<evaluation-passed>/,
-  evaluation_failed: /<evaluation-failed>([\s\S]*?)<\/evaluation-failed>/,
-  task_verified: /<task-verified>([\s\S]*?)<\/task-verified>/,
-  task_complete: /<task-complete>/,
-  task_blocked: /<task-blocked>([\s\S]*?)<\/task-blocked>/,
-  note: /<note>([\s\S]*?)<\/note>/g
-};
-var DIMENSION_LINE2 = /\*\*([A-Za-z][A-Za-z0-9]{2,29})\*\*\s*:\s*(PASS|FAIL)\s*(?:—|-)\s*(.+)/gi;
-function parseDimensionScores2(output) {
-  const scores = [];
-  const seen = /* @__PURE__ */ new Set();
-  DIMENSION_LINE2.lastIndex = 0;
-  let match;
-  while ((match = DIMENSION_LINE2.exec(output)) !== null) {
-    const rawName = match[1];
-    const verdict = match[2];
-    const finding = match[3];
-    if (!rawName || !verdict || !finding) continue;
-    const name = rawName.toLowerCase();
-    if (seen.has(name)) continue;
-    seen.add(name);
-    scores.push({
-      dimension: name,
-      passed: verdict.toUpperCase() === "PASS",
-      finding: finding.trim()
-    });
-  }
-  return scores;
-}
-var SignalParser = class {
-  parseSignals(output) {
-    const signals = [];
-    const timestamp = /* @__PURE__ */ new Date();
-    let progressMatch;
-    while ((progressMatch = SIGNAL_PATTERNS.progress.exec(output)) !== null) {
-      const summary = progressMatch[1]?.trim();
-      if (summary) {
-        const progressSignal = {
-          type: "progress",
-          summary,
-          // Note: Phase 1 doesn't parse files attribute; added in Phase 2+
-          timestamp
-        };
-        signals.push(progressSignal);
-      }
-    }
-    if (output.includes("<evaluation-passed>")) {
-      const dimensions = parseDimensionScores2(output);
-      const evaluationSignal = {
-        type: "evaluation",
-        status: "passed",
-        dimensions,
-        timestamp
-      };
-      signals.push(evaluationSignal);
-    } else {
-      const failedMatch = SIGNAL_PATTERNS.evaluation_failed.exec(output);
-      if (failedMatch?.[1]) {
-        const critique = failedMatch[1].trim();
-        const dimensions = parseDimensionScores2(output);
-        const evaluationSignal = {
-          type: "evaluation",
-          status: dimensions.length > 0 ? "failed" : "malformed",
-          dimensions,
-          critique: dimensions.length > 0 ? critique : void 0,
-          timestamp
-        };
-        signals.push(evaluationSignal);
-      } else if (parseDimensionScores2(output).length > 0) {
-        const dimensions = parseDimensionScores2(output);
-        const evaluationSignal = {
-          type: "evaluation",
-          status: "failed",
-          dimensions,
-          timestamp
-        };
-        signals.push(evaluationSignal);
-      }
-    }
-    const taskVerifiedMatch = SIGNAL_PATTERNS.task_verified.exec(output);
-    if (taskVerifiedMatch?.[1]) {
-      const verificationOutput = taskVerifiedMatch[1].trim();
-      const verifiedSignal = {
-        type: "task-verified",
-        output: verificationOutput,
-        timestamp
-      };
-      signals.push(verifiedSignal);
-    }
-    if (output.includes("<task-complete>")) {
-      const completeSignal = {
-        type: "task-complete",
-        timestamp
-      };
-      signals.push(completeSignal);
-    }
-    const taskBlockedMatch = SIGNAL_PATTERNS.task_blocked.exec(output);
-    if (taskBlockedMatch?.[1]) {
-      const reason = taskBlockedMatch[1].trim();
-      const blockedSignal = {
-        type: "task-blocked",
-        reason,
-        timestamp
-      };
-      signals.push(blockedSignal);
-    }
-    let noteMatch;
-    while ((noteMatch = SIGNAL_PATTERNS.note.exec(output)) !== null) {
-      const text = noteMatch[1]?.trim();
-      if (text) {
-        const noteSignal = {
-          type: "note",
-          text,
-          timestamp
-        };
-        signals.push(noteSignal);
-      }
-    }
-    return signals;
-  }
-};
-
 // src/integration/ai/output/parser.ts
 var signalParser = new SignalParser();
 function parseExecutionResult(output) {
@@ -4965,8 +4442,8 @@ var AutoUserAdapter = class {
 };
 
 // src/integration/ai/project-tooling.ts
-import { existsSync as existsSync2, readdirSync, readFileSync as readFileSync2 } from "fs";
-import { join as join5 } from "path";
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { join as join3 } from "path";
 var EMPTY_TOOLING = {
   agents: [],
   skills: [],
@@ -4977,7 +4454,7 @@ var EMPTY_TOOLING = {
 };
 function safeListDir(path, predicate) {
   try {
-    if (!existsSync2(path)) return [];
+    if (!existsSync(path)) return [];
     return readdirSync(path).filter(predicate).sort();
   } catch {
     return [];
@@ -4985,23 +4462,23 @@ function safeListDir(path, predicate) {
 }
 var EVALUATOR_DENYLISTED_AGENTS = /* @__PURE__ */ new Set(["implementer", "planner"]);
 function detectAgents(projectPath) {
-  const agentsDir = join5(projectPath, ".claude", "agents");
+  const agentsDir = join3(projectPath, ".claude", "agents");
   return safeListDir(agentsDir, (name) => name.endsWith(".md")).map((name) => name.replace(/\.md$/, "")).filter((name) => !EVALUATOR_DENYLISTED_AGENTS.has(name));
 }
 function detectSkills(projectPath) {
-  const skillsDir = join5(projectPath, ".claude", "skills");
+  const skillsDir = join3(projectPath, ".claude", "skills");
   try {
-    if (!existsSync2(skillsDir)) return [];
+    if (!existsSync(skillsDir)) return [];
     return readdirSync(skillsDir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
   } catch {
     return [];
   }
 }
 function detectMcpServers(projectPath) {
-  const mcpFile = join5(projectPath, ".mcp.json");
-  if (!existsSync2(mcpFile)) return [];
+  const mcpFile = join3(projectPath, ".mcp.json");
+  if (!existsSync(mcpFile)) return [];
   try {
-    const raw = readFileSync2(mcpFile, "utf-8");
+    const raw = readFileSync(mcpFile, "utf-8");
     const parsed = JSON.parse(raw);
     const servers = parsed.mcpServers;
     if (!servers || typeof servers !== "object") return [];
@@ -5011,16 +4488,16 @@ function detectMcpServers(projectPath) {
   }
 }
 function detectProjectTooling(projectPath) {
-  if (!projectPath || !existsSync2(projectPath)) {
+  if (!projectPath || !existsSync(projectPath)) {
     return EMPTY_TOOLING;
   }
   return {
     agents: detectAgents(projectPath),
     skills: detectSkills(projectPath),
     mcpServers: detectMcpServers(projectPath),
-    hasClaudeMd: existsSync2(join5(projectPath, "CLAUDE.md")),
-    hasAgentsMd: existsSync2(join5(projectPath, "AGENTS.md")),
-    hasCopilotInstructions: existsSync2(join5(projectPath, ".github", "copilot-instructions.md"))
+    hasClaudeMd: existsSync(join3(projectPath, "CLAUDE.md")),
+    hasAgentsMd: existsSync(join3(projectPath, "AGENTS.md")),
+    hasCopilotInstructions: existsSync(join3(projectPath, ".github", "copilot-instructions.md"))
   };
 }
 function detectProjectToolingAcrossPaths(projectPaths) {
@@ -5131,7 +4608,7 @@ function describeMcpHint(name) {
 }
 
 // src/integration/external/lifecycle.ts
-import { spawnSync as spawnSync2 } from "child_process";
+import { spawnSync } from "child_process";
 var DEFAULT_HOOK_TIMEOUT_MS = 5 * 60 * 1e3;
 function getHookTimeoutMs() {
   const envVal = process.env["RALPHCTL_SETUP_TIMEOUT_MS"];
@@ -5144,7 +4621,7 @@ function getHookTimeoutMs() {
 function runLifecycleHook(projectPath, script, event, timeoutOverrideMs) {
   assertSafeCwd(projectPath);
   const timeoutMs = timeoutOverrideMs ?? getHookTimeoutMs();
-  const result = spawnSync2(script, {
+  const result = spawnSync(script, {
     cwd: projectPath,
     shell: true,
     stdio: ["pipe", "pipe", "pipe"],
@@ -5158,9 +4635,9 @@ function runLifecycleHook(projectPath, script, event, timeoutOverrideMs) {
 
 // src/integration/ai/task-context.ts
 import { execSync } from "child_process";
-import { Result as Result5 } from "typescript-result";
+import { Result as Result3 } from "typescript-result";
 function getRecentGitHistory(projectPath, count = 20) {
-  const r = Result5.try(() => {
+  const r = Result3.try(() => {
     assertSafeCwd(projectPath);
     const result = execSync(`git log -${String(count)} --oneline --no-decorate`, {
       cwd: projectPath,
@@ -5173,7 +4650,7 @@ function getRecentGitHistory(projectPath, count = 20) {
 }
 
 // src/integration/external/git.ts
-import { spawnSync as spawnSync3 } from "child_process";
+import { spawnSync as spawnSync2 } from "child_process";
 var BRANCH_NAME_RE = /^[a-zA-Z0-9/_.-]+$/;
 var BRANCH_NAME_INVALID_PATTERNS = [/\.\./, /\.$/, /\/$/, /\.lock$/, /^-/, /\/\//];
 function isValidBranchName(name) {
@@ -5186,7 +4663,7 @@ function isValidBranchName(name) {
 }
 function getCurrentBranch(cwd) {
   assertSafeCwd(cwd);
-  const result = spawnSync3("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+  const result = spawnSync2("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
     cwd,
     encoding: "utf-8",
     stdio: ["pipe", "pipe", "pipe"]
@@ -5201,7 +4678,7 @@ function branchExists(cwd, name) {
   if (!isValidBranchName(name)) {
     throw new Error(`Invalid branch name: ${name}`);
   }
-  const result = spawnSync3("git", ["show-ref", "--verify", `refs/heads/${name}`], {
+  const result = spawnSync2("git", ["show-ref", "--verify", `refs/heads/${name}`], {
     cwd,
     encoding: "utf-8",
     stdio: ["pipe", "pipe", "pipe"]
@@ -5218,7 +4695,7 @@ function createAndCheckoutBranch(cwd, name) {
     return;
   }
   if (branchExists(cwd, name)) {
-    const result = spawnSync3("git", ["checkout", name], {
+    const result = spawnSync2("git", ["checkout", name], {
       cwd,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
@@ -5227,7 +4704,7 @@ function createAndCheckoutBranch(cwd, name) {
       throw new Error(`Failed to checkout branch '${name}' in ${cwd}: ${result.stderr.trim()}`);
     }
   } else {
-    const result = spawnSync3("git", ["checkout", "-b", name], {
+    const result = spawnSync2("git", ["checkout", "-b", name], {
       cwd,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
@@ -5243,7 +4720,7 @@ function verifyCurrentBranch(cwd, expected) {
 }
 function getDefaultBranch(cwd) {
   assertSafeCwd(cwd);
-  const result = spawnSync3("git", ["symbolic-ref", "refs/remotes/origin/HEAD"], {
+  const result = spawnSync2("git", ["symbolic-ref", "refs/remotes/origin/HEAD"], {
     cwd,
     encoding: "utf-8",
     stdio: ["pipe", "pipe", "pipe"]
@@ -5264,7 +4741,7 @@ function getDefaultBranch(cwd) {
 function getHeadSha(cwd) {
   try {
     assertSafeCwd(cwd);
-    const result = spawnSync3("git", ["rev-parse", "HEAD"], {
+    const result = spawnSync2("git", ["rev-parse", "HEAD"], {
       cwd,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
@@ -5277,7 +4754,7 @@ function getHeadSha(cwd) {
 }
 function hasUncommittedChanges(cwd) {
   assertSafeCwd(cwd);
-  const result = spawnSync3("git", ["status", "--porcelain"], {
+  const result = spawnSync2("git", ["status", "--porcelain"], {
     cwd,
     encoding: "utf-8",
     stdio: ["pipe", "pipe", "pipe"]
@@ -5287,9 +4764,28 @@ function hasUncommittedChanges(cwd) {
   }
   return result.stdout.trim().length > 0;
 }
+function hardResetWorkingTree(cwd) {
+  assertSafeCwd(cwd);
+  const reset = spawnSync2("git", ["reset", "--hard", "HEAD"], {
+    cwd,
+    encoding: "utf-8",
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+  if (reset.status !== 0) {
+    throw new StorageError(`Failed to reset working tree in ${cwd}: ${reset.stderr.trim() || reset.stdout.trim()}`);
+  }
+  const clean = spawnSync2("git", ["clean", "-fd"], {
+    cwd,
+    encoding: "utf-8",
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+  if (clean.status !== 0) {
+    throw new StorageError(`Failed to clean working tree in ${cwd}: ${clean.stderr.trim() || clean.stdout.trim()}`);
+  }
+}
 function autoCommit(cwd, message) {
   assertSafeCwd(cwd);
-  const add = spawnSync3("git", ["add", "-A"], {
+  const add = spawnSync2("git", ["add", "-A"], {
     cwd,
     encoding: "utf-8",
     stdio: ["pipe", "pipe", "pipe"]
@@ -5297,7 +4793,7 @@ function autoCommit(cwd, message) {
   if (add.status !== 0) {
     throw new Error(`Failed to stage changes in ${cwd}: ${add.stderr.trim()}`);
   }
-  const commit = spawnSync3("git", ["commit", "-m", message], {
+  const commit = spawnSync2("git", ["commit", "-m", message], {
     cwd,
     encoding: "utf-8",
     stdio: ["pipe", "pipe", "pipe"]
@@ -5310,14 +4806,14 @@ function generateBranchName(sprintId) {
   return `ralphctl/${sprintId}`;
 }
 function isGhAvailable() {
-  const result = spawnSync3("gh", ["--version"], {
+  const result = spawnSync2("gh", ["--version"], {
     encoding: "utf-8",
     stdio: ["pipe", "pipe", "pipe"]
   });
   return result.status === 0;
 }
 function isGlabAvailable() {
-  const result = spawnSync3("glab", ["--version"], {
+  const result = spawnSync2("glab", ["--version"], {
     encoding: "utf-8",
     stdio: ["pipe", "pipe", "pipe"]
   });
@@ -5365,6 +4861,9 @@ var DefaultExternalAdapter = class {
   hasUncommittedChanges(projectPath) {
     return hasUncommittedChanges(projectPath);
   }
+  hardResetWorkingTree(projectPath) {
+    hardResetWorkingTree(projectPath);
+  }
   autoCommit(projectPath, message) {
     autoCommit(projectPath, message);
     return Promise.resolve();
@@ -5392,6 +4891,265 @@ var DefaultExternalAdapter = class {
   }
 };
 
+// src/integration/external/onboard-adapter.ts
+import { existsSync as existsSync4, statSync } from "fs";
+import { join as join6 } from "path";
+
+// src/integration/external/agents-md-linter.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { join as join4 } from "path";
+var MAX_H2 = 7;
+var MAX_LINES = 300;
+var MIN_FLESCH = 40;
+var REQUIRED_H2_SECTIONS = [
+  "Project Overview",
+  "Build & Run",
+  "Testing",
+  "Architecture",
+  "Implementation Style",
+  "Security & Safety",
+  "Performance Constraints"
+];
+function normalizeHeading(raw) {
+  return raw.replace(/^#+\s*/, "").replace(/[*_`]/g, "").trim().toLowerCase();
+}
+function lintAgentsMd(content) {
+  const violations = [];
+  const lines = content.split("\n");
+  if (lines.length >= MAX_LINES) {
+    violations.push({
+      rule: "max-lines",
+      message: `Project context file is ${String(lines.length)} lines (must be under ${String(MAX_LINES)}).`
+    });
+  }
+  let inCodeFence = false;
+  let h1Count = 0;
+  let h2Count = 0;
+  const h2Titles = [];
+  for (const line of lines) {
+    if (line.startsWith("```")) {
+      inCodeFence = !inCodeFence;
+      continue;
+    }
+    if (inCodeFence) continue;
+    const match = /^(#+)\s/.exec(line);
+    if (!match) continue;
+    const depth = match[1]?.length ?? 0;
+    if (depth === 1) h1Count++;
+    else if (depth === 2) {
+      h2Count++;
+      h2Titles.push(normalizeHeading(line));
+    } else if (depth >= 4) {
+      violations.push({
+        rule: "no-h4-plus",
+        message: `H${String(depth)} heading is too deep \u2014 keep structure flat (H1/H2/H3 only): "${line.trim()}"`
+      });
+    }
+  }
+  for (const required of REQUIRED_H2_SECTIONS) {
+    if (!h2Titles.includes(required.toLowerCase())) {
+      violations.push({
+        rule: "required-section",
+        message: `Missing required H2 section: "## ${required}".`
+      });
+    }
+  }
+  if (h1Count !== 1) {
+    violations.push({
+      rule: "single-h1",
+      message: `Expected exactly one H1, found ${String(h1Count)}.`
+    });
+  }
+  if (h2Count > MAX_H2) {
+    violations.push({
+      rule: "max-h2",
+      message: `Too many H2 sections (${String(h2Count)}); keep at most ${String(MAX_H2)}.`
+    });
+  }
+  const flesch = fleschReadingEase(content);
+  if (Number.isFinite(flesch) && flesch < MIN_FLESCH) {
+    violations.push({
+      rule: "readability",
+      message: `Flesch score ${flesch.toFixed(1)} is below ${String(MIN_FLESCH)} \u2014 simplify long sentences.`
+    });
+  }
+  return { ok: violations.length === 0, violations };
+}
+function fleschReadingEase(content) {
+  const prose = stripNonProse(content);
+  const words = prose.match(/[A-Za-z][A-Za-z'-]*/g) ?? [];
+  if (words.length === 0) return 100;
+  const sentences = Math.max(1, (prose.match(/[.!?]+(?:\s|$)/g) ?? []).length);
+  const syllables = words.reduce((sum, w) => sum + countSyllables(w), 0);
+  return 206.835 - 1.015 * (words.length / sentences) - 84.6 * (syllables / words.length);
+}
+function stripNonProse(content) {
+  return content.replace(/```[\s\S]*?```/g, " ").replace(/`[^`]*`/g, " ").replace(/^#+\s+.*$/gm, " ").replace(/^\s*[-*+]\s+/gm, "");
+}
+function countSyllables(word) {
+  const lower = word.toLowerCase();
+  const groups = lower.match(/[aeiouy]+/g) ?? [];
+  let count = groups.length;
+  if (lower.at(-1) === "e" && count > 1) count--;
+  return Math.max(1, count);
+}
+function detectCommandDrift(content, repoPath) {
+  const warnings = [];
+  const pkgPath = join4(repoPath, "package.json");
+  if (!existsSync2(pkgPath)) return warnings;
+  let scripts = {};
+  try {
+    const raw = readFileSync2(pkgPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (isRecord(parsed) && isRecord(parsed["scripts"])) {
+      const entries = Object.entries(parsed["scripts"]).filter((pair) => {
+        return typeof pair[1] === "string";
+      });
+      scripts = Object.fromEntries(entries);
+    }
+  } catch {
+    return warnings;
+  }
+  const re = /\b(?:npm|pnpm|yarn)\s+(?:run\s+)?([a-z][a-z0-9:_-]*)/gi;
+  let match;
+  const seen = /* @__PURE__ */ new Set();
+  while ((match = re.exec(content)) !== null) {
+    const name = match[1];
+    if (!name) continue;
+    if (seen.has(name)) continue;
+    seen.add(name);
+    if (name === "install" || name === "test" || name === "start") continue;
+    if (!(name in scripts)) {
+      warnings.push(`Referenced script "${name}" not defined in package.json`);
+    }
+  }
+  return warnings;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+
+// src/integration/external/agents-md-writer.ts
+import { existsSync as existsSync3, mkdirSync, readFileSync as readFileSync3, renameSync, writeFileSync } from "fs";
+import { dirname, join as join5 } from "path";
+import { randomBytes } from "crypto";
+var RALPHCTL_MARKER = "<!-- managed by ralphctl onboard -->";
+function providerInstructionsPath(repoPath, provider) {
+  if (provider === "claude") return join5(repoPath, "CLAUDE.md");
+  return join5(repoPath, ".github", "copilot-instructions.md");
+}
+function readExistingProviderInstructions(repoPath, provider) {
+  const path = providerInstructionsPath(repoPath, provider);
+  if (!existsSync3(path)) return { content: null, authored: false };
+  let content;
+  try {
+    content = readFileSync3(path, "utf-8");
+  } catch {
+    return { content: null, authored: false };
+  }
+  const managed = content.includes(RALPHCTL_MARKER);
+  return { content, authored: !managed };
+}
+function writeProviderInstructionsAtomic(repoPath, content, provider) {
+  const target = providerInstructionsPath(repoPath, provider);
+  mkdirSync(dirname(target), { recursive: true });
+  const body = content.endsWith("\n") ? content : `${content}
+`;
+  const stamped = body.includes(RALPHCTL_MARKER) ? body : `${body}
+${RALPHCTL_MARKER}
+`;
+  const tempPath = `${target}.${randomBytes(6).toString("hex")}.tmp`;
+  writeFileSync(tempPath, stamped, { encoding: "utf-8", mode: 420 });
+  renameSync(tempPath, target);
+  return { path: target };
+}
+
+// src/integration/ai/discover-agents-md.ts
+var DISCOVERY_TIMEOUT_MS = 12e4;
+async function discoverAgentsMdWithAi(ctx, aiSession, signalParser2) {
+  const prompt = buildRepoOnboardPrompt(ctx);
+  const session = aiSession.spawnHeadless(prompt, { cwd: ctx.repoPath });
+  const timeout = new Promise((resolve) => {
+    setTimeout(() => {
+      resolve(null);
+    }, DISCOVERY_TIMEOUT_MS).unref();
+  });
+  try {
+    const result = await Promise.race([session, timeout]);
+    if (!result) return { agentsMd: null, checkScript: null, changes: null };
+    const signals = signalParser2.parseSignals(result.output);
+    const agentsSignal = signals.find((s) => s.type === "agents-md-proposal");
+    const checkSignal = signals.find((s) => s.type === "check-script-discovery");
+    const changes = extractChanges(result.output);
+    return {
+      agentsMd: agentsSignal ? agentsSignal.content : null,
+      checkScript: checkSignal ? checkSignal.command : null,
+      changes
+    };
+  } catch {
+    return { agentsMd: null, checkScript: null, changes: null };
+  }
+}
+function extractChanges(output) {
+  const match = /<changes>([\s\S]*?)<\/changes>/.exec(output);
+  if (!match?.[1]) return null;
+  const body = match[1].trim();
+  return body.length > 0 ? body : null;
+}
+
+// src/integration/external/onboard-adapter.ts
+var DefaultOnboardAdapter = class {
+  constructor(aiSession, signalParser2) {
+    this.aiSession = aiSession;
+    this.signalParser = signalParser2;
+  }
+  aiSession;
+  signalParser;
+  readExistingInstructions(repoPath, provider) {
+    return readExistingProviderInstructions(repoPath, provider);
+  }
+  validateRepoPath(path) {
+    let exists;
+    try {
+      exists = existsSync4(path) && statSync(path).isDirectory();
+    } catch {
+      exists = false;
+    }
+    if (!exists) return { exists: false, isGitRepo: false };
+    const isGitRepo = existsSync4(join6(path, ".git"));
+    return { exists: true, isGitRepo };
+  }
+  lintAgentsMd(content) {
+    return lintAgentsMd(content);
+  }
+  detectCommandDrift(content, repoPath) {
+    return detectCommandDrift(content, repoPath);
+  }
+  async discoverAgentsMd(input) {
+    return discoverAgentsMdWithAi(input, this.aiSession, this.signalParser);
+  }
+  inferProjectType(repoPath) {
+    const checks = [
+      ["package.json", "node"],
+      ["pyproject.toml", "python"],
+      ["requirements.txt", "python"],
+      ["Cargo.toml", "rust"],
+      ["go.mod", "go"],
+      ["pom.xml", "java"],
+      ["build.gradle", "java"],
+      ["Makefile", "makefile"]
+    ];
+    const hints = [];
+    for (const [file, label] of checks) {
+      if (existsSync4(join6(repoPath, file))) hints.push(label);
+    }
+    return hints.length === 0 ? "unknown" : hints.join(", ");
+  }
+  writeProviderInstructions(repoPath, content, provider) {
+    return writeProviderInstructionsAtomic(repoPath, content, provider);
+  }
+};
+
 // src/application/factories.ts
 function createAiDeps(auto) {
   return {
@@ -5451,6 +5209,22 @@ function createIdeatePipeline2(shared, idea, options = {}) {
     options
   );
 }
+function createOnboardPipeline2(shared, options = {}) {
+  const aiSession = new ProviderAiSessionAdapter();
+  const adapter = new DefaultOnboardAdapter(aiSession, shared.signalParser);
+  return createOnboardPipeline(
+    {
+      persistence: shared.persistence,
+      adapter,
+      logger: shared.logger,
+      prompt: shared.prompt,
+      updateProjectRepos: async (name, repositories) => {
+        return updateProject(name, { repositories });
+      }
+    },
+    options
+  );
+}
 function createExecuteSprintPipeline2(shared, options = {}) {
   const { aiSession, promptBuilder, parser, ui, external } = createAiDeps(false);
   return createExecuteSprintPipeline(
@@ -5467,7 +5241,9 @@ function createExecuteSprintPipeline2(shared, options = {}) {
       signalHandler: shared.signalHandler,
       signalBus: shared.signalBus,
       createRateLimitCoordinator: shared.createRateLimitCoordinator,
-      processLifecycle: shared.processLifecycle
+      processLifecycle: shared.processLifecycle,
+      prompt: shared.prompt,
+      isTTY
     },
     options
   );
@@ -5547,10 +5323,17 @@ function parseArgs(args) {
       options.noEvaluate = true;
     } else if (arg === "--no-feedback") {
       options.noFeedback = true;
+    } else if (arg === "--resume-dirty") {
+      options.resumeDirty = true;
+    } else if (arg === "--reset-on-resume") {
+      options.resetOnResume = true;
     } else if (!arg?.startsWith("-")) {
       sprintId = arg;
     }
   }
+  if (options.resumeDirty && options.resetOnResume) {
+    throw new Error("--resume-dirty and --reset-on-resume are mutually exclusive");
+  }
   return { sprintId, options };
 }
 async function sprintStartCommand(args) {
@@ -5629,6 +5412,7 @@ async function sprintStartCommand(args) {
 }
 
 export {
+  executePipeline,
   getTasks,
   saveTasks,
   getTask,
@@ -5644,29 +5428,20 @@ export {
   areAllTasksDone,
   reorderByDependencies,
   validateImportTasks,
-  getCurrentBranch,
-  branchExists,
-  getDefaultBranch,
-  isGhAvailable,
-  isGlabAvailable,
-  executePipeline,
-  processLifecycleAdapter,
-  resolveProvider,
-  providerDisplayName,
-  enterAltScreen,
-  exitAltScreen,
-  registerTuiInstance,
-  withSuspendedTui,
-  buildTicketRefinePrompt,
   renderParsedTasksTable,
   importTasks,
   formatTicketForPrompt,
   parseRequirementsFile,
   runAiSession,
-  SignalParser,
+  getCurrentBranch,
+  branchExists,
+  getDefaultBranch,
+  isGhAvailable,
+  isGlabAvailable,
   createRefinePipeline2 as createRefinePipeline,
   createPlanPipeline2 as createPlanPipeline,
   createIdeatePipeline2 as createIdeatePipeline,
+  createOnboardPipeline2 as createOnboardPipeline,
   createExecuteSprintPipeline2 as createExecuteSprintPipeline,
   parseSprintStartArgs,
   sprintStartCommand