lsd-pi 1.0.0 → 1.1.0

package/src/resources/extensions/gsd/workflow-reconcile.ts

@@ -1,532 +0,0 @@
-import { join } from "node:path";
-import { mkdirSync, existsSync, readFileSync, unlinkSync } from "node:fs";
-import { logWarning, logError } from "./workflow-logger.js";
-import { readEvents, findForkPoint, appendEvent, getSessionId } from "./workflow-events.js";
-import type { WorkflowEvent } from "./workflow-events.js";
-import {
-  transaction,
-  updateTaskStatus,
-  updateSliceStatus,
-  getSliceTasks,
-  insertVerificationEvidence,
-  upsertDecision,
-  openDatabase,
-} from "./gsd-db.js";
-import { isClosedStatus } from "./status-guards.js";
-import { writeManifest } from "./workflow-manifest.js";
-import { atomicWriteSync } from "./atomic-write.js";
-import { acquireSyncLock, releaseSyncLock } from "./sync-lock.js";
-
-// ─── Replay Helpers ──────────────────────────────────────────────────────────
-
-/**
- * Replay a complete_slice event with task validation.
- *
- * #2945 Bug 2: The original replay blindly called updateSliceStatus("done")
- * without checking whether all tasks in the slice are actually complete.
- * During API overload or partial execution, a complete_slice event could
- * be logged even when tasks were skipped, causing the milestone completion
- * guard to see the slice as "done" and allow premature milestone completion.
- *
- * This function validates that every task in the slice has a closed status
- * before marking the slice as done. If any task is still pending, the slice
- * status is left unchanged.
- */
-export function replaySliceComplete(milestoneId: string, sliceId: string, ts: string): void {
-  const tasks = getSliceTasks(milestoneId, sliceId);
-  // If there are tasks and any are not closed, skip the status update
-  if (tasks.length > 0) {
-    const incompleteTasks = tasks.filter(t => !isClosedStatus(t.status));
-    if (incompleteTasks.length > 0) {
-      process.stderr.write(
-        `[gsd] reconcile: skipping complete_slice replay for ${sliceId} — ` +
-        `${incompleteTasks.length} task(s) still pending\n`,
-      );
-      return;
-    }
-  }
-  updateSliceStatus(milestoneId, sliceId, "done", ts);
-}
-
-// ─── Public Types ─────────────────────────────────────────────────────────────
-
-export interface ConflictEntry {
-  entityType: string;
-  entityId: string;
-  mainSideEvents: WorkflowEvent[];
-  worktreeSideEvents: WorkflowEvent[];
-}
-
-export interface ReconcileResult {
-  autoMerged: number;
-  conflicts: ConflictEntry[];
-}
-
-// ─── replayEvents ─────────────────────────────────────────────────────────────
-
-/**
- * Replay a list of WorkflowEvents by dispatching each to the appropriate
- * gsd-db function.  This replaces the old engine.replayAll() pattern with
- * direct DB calls.
- */
-function replayEvents(events: WorkflowEvent[]): void {
-  transaction(() => {
-  for (const event of events) {
-    const p = event.params;
-    switch (event.cmd) {
-      case "complete_task": {
-        const milestoneId = p["milestoneId"] as string;
-        const sliceId = p["sliceId"] as string;
-        const taskId = p["taskId"] as string;
-        updateTaskStatus(milestoneId, sliceId, taskId, "done", event.ts);
-        break;
-      }
-      case "start_task": {
-        const milestoneId = p["milestoneId"] as string;
-        const sliceId = p["sliceId"] as string;
-        const taskId = p["taskId"] as string;
-        updateTaskStatus(milestoneId, sliceId, taskId, "in-progress", event.ts);
-        break;
-      }
-      case "report_blocker": {
-        // report_blocker marks the task with blocker_discovered = 1
-        // The DB helper updateTaskStatus doesn't handle blockers,
-        // so we just update status to "blocked" as a best-effort replay.
-        const milestoneId = p["milestoneId"] as string;
-        const sliceId = p["sliceId"] as string;
-        const taskId = p["taskId"] as string;
-        updateTaskStatus(milestoneId, sliceId, taskId, "blocked");
-        break;
-      }
-      case "record_verification": {
-        const milestoneId = p["milestoneId"] as string;
-        const sliceId = p["sliceId"] as string;
-        const taskId = p["taskId"] as string;
-        insertVerificationEvidence({
-          taskId,
-          sliceId,
-          milestoneId,
-          command: (p["command"] as string) ?? "",
-          exitCode: (p["exitCode"] as number) ?? 0,
-          verdict: (p["verdict"] as string) ?? "",
-          durationMs: (p["durationMs"] as number) ?? 0,
-        });
-        break;
-      }
-      case "complete_slice": {
-        const milestoneId = p["milestoneId"] as string;
-        const sliceId = p["sliceId"] as string;
-        // #2945 Bug 2: validate tasks before marking slice done
-        replaySliceComplete(milestoneId, sliceId, event.ts);
-        break;
-      }
-      case "plan_slice": {
-        // plan_slice events are informational — slice should already exist.
-        // No DB mutation needed during replay (the slice was inserted at plan time).
-        break;
-      }
-      case "save_decision": {
-        upsertDecision({
-          id: (p["id"] as string) ?? `${p["scope"]}:${p["decision"]}`,
-          when_context: (p["when_context"] as string) ?? (p["whenContext"] as string) ?? "",
-          scope: (p["scope"] as string) ?? "",
-          decision: (p["decision"] as string) ?? "",
-          choice: (p["choice"] as string) ?? "",
-          rationale: (p["rationale"] as string) ?? "",
-          revisable: (p["revisable"] as string) ?? "yes",
-          made_by: ((p["made_by"] as string) ?? (p["madeBy"] as string) ?? "agent") as "agent",
-          superseded_by: (p["superseded_by"] as string) ?? (p["supersededBy"] as string) ?? null,
-        });
-        break;
-      }
-      default:
-        // Unknown commands are silently skipped during replay
-        break;
-    }
-  }
-  }); // end transaction
-}
-
-// ─── extractEntityKey ─────────────────────────────────────────────────────────
-
-/**
- * Map a WorkflowEvent command to its affected entity type and ID.
- * Returns null for commands that don't touch a named entity
- * (e.g. unknown or future cmds).
- */
-export function extractEntityKey(
-  event: WorkflowEvent,
-): { type: string; id: string } | null {
-  const p = event.params;
-
-  switch (event.cmd) {
-    case "complete_task":
-    case "start_task":
-    case "report_blocker":
-    case "record_verification":
-      return typeof p["taskId"] === "string"
-        ? { type: "task", id: p["taskId"] }
-        : null;
-
-    case "complete_slice":
-      return typeof p["sliceId"] === "string"
-        ? { type: "slice", id: p["sliceId"] }
-        : null;
-
-    case "plan_slice":
-      return typeof p["sliceId"] === "string"
-        ? { type: "slice_plan", id: p["sliceId"] }
-        : null;
-
-    case "save_decision":
-      if (typeof p["scope"] === "string" && typeof p["decision"] === "string") {
-        return { type: "decision", id: `${p["scope"]}:${p["decision"]}` };
-      }
-      return null;
-
-    default:
-      return null;
-  }
-}
-
-// ─── detectConflicts ──────────────────────────────────────────────────────────
-
-/**
- * Compare two sets of diverged events. Returns conflict entries for any
- * entity touched by both sides.
- *
- * Entity-level granularity: if both sides touched task T01 (with any cmd),
- * that is one conflict regardless of field-level differences.
- */
-export function detectConflicts(
-  mainDiverged: WorkflowEvent[],
-  wtDiverged: WorkflowEvent[],
-): ConflictEntry[] {
-  // Group each side's events by entity key
-  const mainByEntity = new Map<string, WorkflowEvent[]>();
-  for (const event of mainDiverged) {
-    const key = extractEntityKey(event);
-    if (!key) continue;
-    const bucket = mainByEntity.get(`${key.type}:${key.id}`) ?? [];
-    bucket.push(event);
-    mainByEntity.set(`${key.type}:${key.id}`, bucket);
-  }
-
-  const wtByEntity = new Map<string, WorkflowEvent[]>();
-  for (const event of wtDiverged) {
-    const key = extractEntityKey(event);
-    if (!key) continue;
-    const bucket = wtByEntity.get(`${key.type}:${key.id}`) ?? [];
-    bucket.push(event);
-    wtByEntity.set(`${key.type}:${key.id}`, bucket);
-  }
-
-  // Find entities touched by both sides
-  const conflicts: ConflictEntry[] = [];
-  for (const [entityKey, mainEvents] of mainByEntity) {
-    const wtEvents = wtByEntity.get(entityKey);
-    if (!wtEvents) continue;
-
-    const colonIdx = entityKey.indexOf(":");
-    const entityType = entityKey.slice(0, colonIdx);
-    const entityId = entityKey.slice(colonIdx + 1);
-
-    conflicts.push({
-      entityType,
-      entityId,
-      mainSideEvents: mainEvents,
-      worktreeSideEvents: wtEvents,
-    });
-  }
-
-  return conflicts;
-}
-
-// ─── writeConflictsFile ───────────────────────────────────────────────────────
-
-/**
- * Write a human-readable CONFLICTS.md to basePath/.gsd/CONFLICTS.md.
- * Lists each conflict with both sides' event payloads and resolution instructions.
- */
-export function writeConflictsFile(
-  basePath: string,
-  conflicts: ConflictEntry[],
-  worktreePath: string,
-): void {
-  const timestamp = new Date().toISOString();
-  const lines: string[] = [
-    `# Merge Conflicts — ${timestamp}`,
-    "",
-    `Conflicts detected merging worktree \`${worktreePath}\` into \`${basePath}\`.`,
-    `Run \`gsd resolve-conflict\` to resolve each conflict.`,
-    "",
-  ];
-
-  conflicts.forEach((conflict, idx) => {
-    lines.push(`## Conflict ${idx + 1}: ${conflict.entityType} ${conflict.entityId}`);
-    lines.push("");
-    lines.push("**Main side events:**");
-    for (const event of conflict.mainSideEvents) {
-      lines.push(`- ${event.cmd} at ${event.ts} (hash: ${event.hash})`);
-      lines.push(`  params: ${JSON.stringify(event.params)}`);
-    }
-    lines.push("");
-    lines.push("**Worktree side events:**");
-    for (const event of conflict.worktreeSideEvents) {
-      lines.push(`- ${event.cmd} at ${event.ts} (hash: ${event.hash})`);
-      lines.push(`  params: ${JSON.stringify(event.params)}`);
-    }
-    lines.push("");
-    lines.push(`**Resolve with:** \`gsd resolve-conflict --entity ${conflict.entityType}:${conflict.entityId} --pick [main|worktree]\``);
-    lines.push("");
-  });
-
-  const content = lines.join("\n");
-  const dir = join(basePath, ".gsd");
-  mkdirSync(dir, { recursive: true });
-  atomicWriteSync(join(dir, "CONFLICTS.md"), content);
-}
-
-// ─── reconcileWorktreeLogs ────────────────────────────────────────────────────
-
-/**
- * Event-log-based reconciliation algorithm:
- *
- * 1. Read both event logs
- * 2. Find fork point (last common event by hash)
- * 3. Slice diverged sets from each side
- * 4. If no divergence on either side → return autoMerged: 0, conflicts: []
- * 5. detectConflicts() — if any, writeConflictsFile + return early (D-04 all-or-nothing)
- * 6. If clean: sort merged = mainDiverged + wtDiverged by timestamp, replayAll
- * 7. Write merged event log (base + merged in timestamp order)
- * 8. writeManifest
- * 9. Return { autoMerged: merged.length, conflicts: [] }
- */
-export function reconcileWorktreeLogs(
-  mainBasePath: string,
-  worktreeBasePath: string,
-): ReconcileResult {
-  // Acquire advisory lock to prevent concurrent reconcile + append races
-  const lock = acquireSyncLock(mainBasePath);
-  if (!lock.acquired) {
-    logWarning("reconcile", "could not acquire sync lock — another reconciliation may be in progress");
-    return { autoMerged: 0, conflicts: [] };
-  }
-
-  try {
-    return _reconcileWorktreeLogsInner(mainBasePath, worktreeBasePath);
-  } finally {
-    releaseSyncLock(mainBasePath);
-  }
-}
-
-function _reconcileWorktreeLogsInner(
-  mainBasePath: string,
-  worktreeBasePath: string,
-): ReconcileResult {
-  // Step 1: Read both logs
-  const mainLogPath = join(mainBasePath, ".gsd", "event-log.jsonl");
-  const wtLogPath = join(worktreeBasePath, ".gsd", "event-log.jsonl");
-
-  const mainEvents = readEvents(mainLogPath);
-  const wtEvents = readEvents(wtLogPath);
-
-  // Step 2: Find fork point
-  const forkPoint = findForkPoint(mainEvents, wtEvents);
-
-  // Step 3: Slice diverged sets
-  const mainDiverged = mainEvents.slice(forkPoint + 1);
-  const wtDiverged = wtEvents.slice(forkPoint + 1);
-
-  // Step 4: No divergence on either side
-  if (mainDiverged.length === 0 && wtDiverged.length === 0) {
-    return { autoMerged: 0, conflicts: [] };
-  }
-
-  // Step 5: Detect conflicts (entity-level)
-  const conflicts = detectConflicts(mainDiverged, wtDiverged);
-  if (conflicts.length > 0) {
-    // D-04: atomic all-or-nothing — block entire merge
-    writeConflictsFile(mainBasePath, conflicts, worktreeBasePath);
-    logError("reconcile", `${conflicts.length} conflict(s) detected`, { count: String(conflicts.length), path: join(mainBasePath, ".gsd", "CONFLICTS.md") });
-    return { autoMerged: 0, conflicts };
-  }
-
-  // Step 6: Clean merge — stable sort by timestamp (index-based tiebreaker)
-  const indexed = [...mainDiverged, ...wtDiverged].map((e, i) => ({ e, i }));
-  indexed.sort((a, b) => a.e.ts.localeCompare(b.e.ts) || a.i - b.i);
-  const merged = indexed.map(({ e }) => e);
-
-  // Step 7: Write merged event log FIRST (so crash recovery can re-derive DB state)
-  const baseEvents = mainEvents.slice(0, forkPoint + 1);
-  const mergedLog = baseEvents.concat(merged);
-  const logContent = mergedLog.map((e) => JSON.stringify(e)).join("\n") + (mergedLog.length > 0 ? "\n" : "");
-  mkdirSync(join(mainBasePath, ".gsd"), { recursive: true });
-  atomicWriteSync(join(mainBasePath, ".gsd", "event-log.jsonl"), logContent);
-
-  // Step 8: Replay into DB (wrapped in a transaction by replayEvents)
-  openDatabase(join(mainBasePath, ".gsd", "gsd.db"));
-  replayEvents(merged);
-
-  // Step 9: Write manifest
-  try {
-    writeManifest(mainBasePath);
-  } catch (err) {
-    logWarning("reconcile", "manifest write failed (non-fatal)", { error: (err as Error).message });
-  }
-
-  return { autoMerged: merged.length, conflicts: [] };
-}
-
-// ─── Conflict Resolution (D-06) ─────────────────────────────────────────────
-
-/**
- * Parse CONFLICTS.md and return structured ConflictEntry[].
- * Returns empty array when CONFLICTS.md does not exist.
- *
- * Parses the format written by writeConflictsFile:
- *   ## Conflict N: {entityType} {entityId}
- *   **Main side events:**
- *   - {cmd} at {ts} (hash: {hash})
- *     params: {JSON}
- *   **Worktree side events:**
- *   - {cmd} at {ts} (hash: {hash})
- *     params: {JSON}
- */
-export function listConflicts(basePath: string): ConflictEntry[] {
-  const conflictsPath = join(basePath, ".gsd", "CONFLICTS.md");
-  if (!existsSync(conflictsPath)) return [];
-
-  const content = readFileSync(conflictsPath, "utf-8");
-  const conflicts: ConflictEntry[] = [];
-
-  // Split into per-conflict sections on "## Conflict N:" headings
-  const sections = content.split(/^## Conflict \d+:/m).slice(1);
-
-  for (const section of sections) {
-    // Extract entity type and id from first line: " {entityType} {entityId}"
-    const headingMatch = section.match(/^\s+(\S+)\s+(\S+)/);
-    if (!headingMatch) continue;
-    const entityType = headingMatch[1]!;
-    const entityId = headingMatch[2]!;
-
-    // Split into main/worktree blocks
-    const mainMatch = section.split("**Main side events:**")[1];
-    const wtMatch = mainMatch?.split("**Worktree side events:**");
-
-    const mainBlock = wtMatch?.[0] ?? "";
-    const wtBlock = wtMatch?.[1] ?? "";
-
-    const mainSideEvents = parseEventBlock(mainBlock);
-    const worktreeSideEvents = parseEventBlock(wtBlock);
-
-    conflicts.push({ entityType, entityId, mainSideEvents, worktreeSideEvents });
-  }
-
-  return conflicts;
-}
-
-/**
- * Parse a block of event lines from CONFLICTS.md into WorkflowEvent[].
- * Each event spans two lines:
- *   - {cmd} at {ts} (hash: {hash})
- *     params: {JSON}
- */
-function parseEventBlock(block: string): WorkflowEvent[] {
-  const events: WorkflowEvent[] = [];
-  // Find lines starting with "- " (event lines)
-  const lines = block.split("\n");
-  let i = 0;
-  while (i < lines.length) {
-    const line = lines[i]!.trim();
-    if (line.startsWith("- ")) {
-      // Parse: - {cmd} at {ts} (hash: {hash})
-      const eventMatch = line.match(/^-\s+(\S+)\s+at\s+(\S+)\s+\(hash:\s+(\S+)\)$/);
-      if (eventMatch) {
-        const cmd = eventMatch[1]!;
-        const ts = eventMatch[2]!;
-        const hash = eventMatch[3]!;
-
-        // Next line: "  params: {JSON}"
-        let params: Record<string, unknown> = {};
-        const nextLine = lines[i + 1];
-        if (nextLine) {
-          const paramsMatch = nextLine.trim().match(/^params:\s+(.+)$/);
-          if (paramsMatch) {
-            try {
-              params = JSON.parse(paramsMatch[1]!) as Record<string, unknown>;
-            } catch {
-              // Keep empty params on parse error
-            }
-            i++; // consume params line
-          }
-        }
-
-        events.push({ cmd, params, ts, hash, actor: "agent", session_id: getSessionId() });
-      }
-    }
-    i++;
-  }
-  return events;
-}
-
-/**
- * Resolve a single conflict by picking one side's events.
- * Replays the picked events through the DB helpers, appends them to the event log,
- * and updates or removes CONFLICTS.md.
- *
- * When the last conflict is resolved, non-conflicting events from both sides
- * are also replayed (they were blocked by the all-or-nothing D-04 rule).
- */
-export function resolveConflict(
-  basePath: string,
-  worktreeBasePath: string,
-  entityKey: string,  // e.g. "task:T01"
-  pick: "main" | "worktree",
-): void {
-  const conflicts = listConflicts(basePath);
-  const colonIdx = entityKey.indexOf(":");
-  const entityType = entityKey.slice(0, colonIdx);
-  const entityId = entityKey.slice(colonIdx + 1);
-
-  const idx = conflicts.findIndex((c) => c.entityType === entityType && c.entityId === entityId);
-  if (idx === -1) throw new Error(`No conflict found for entity ${entityKey}`);
-
-  const conflict = conflicts[idx]!;
-  const eventsToReplay = pick === "main" ? conflict.mainSideEvents : conflict.worktreeSideEvents;
-
-  // Replay resolved events through the DB (updates DB state)
-  openDatabase(join(basePath, ".gsd", "gsd.db"));
-  replayEvents(eventsToReplay);
-
-  // Append resolved events to the event log
-  for (const event of eventsToReplay) {
-    appendEvent(basePath, { cmd: event.cmd, params: event.params, ts: event.ts, actor: event.actor });
-  }
-
-  // Remove resolved conflict from list
-  conflicts.splice(idx, 1);
-
-  if (conflicts.length === 0) {
-    // All conflicts resolved — remove CONFLICTS.md and re-run reconciliation
-    // to pick up non-conflicting events that were blocked by D-04 all-or-nothing.
-    removeConflictsFile(basePath);
-    if (worktreeBasePath) {
-      reconcileWorktreeLogs(basePath, worktreeBasePath);
-    }
-  } else {
-    // Re-write CONFLICTS.md with remaining conflicts
-    writeConflictsFile(basePath, conflicts, worktreeBasePath);
-  }
-}
-
-/**
- * Remove CONFLICTS.md — called when all conflicts are resolved.
- * No-op if CONFLICTS.md does not exist.
- */
-export function removeConflictsFile(basePath: string): void {
-  const conflictsPath = join(basePath, ".gsd", "CONFLICTS.md");
-  if (existsSync(conflictsPath)) {
-    unlinkSync(conflictsPath);
-  }
-}

package/src/resources/extensions/gsd/workflow-templates/bugfix.md

@@ -1,87 +0,0 @@
-# Bugfix Workflow
-
-<template_meta>
-name: bugfix
-version: 1
-requires_project: false
-artifact_dir: .gsd/workflows/bugfixes/
-</template_meta>
-
-<purpose>
-Fix a bug from identification through to PR submission. Designed for issues reported
-via GitHub, user reports, or developer discovery. Emphasizes root cause analysis
-before jumping to fixes.
-</purpose>
-
-<phases>
-1. triage    — Identify root cause, reproduce the bug
-2. fix       — Implement the fix with tests
-3. verify    — Run full test suite, check for regressions
-4. ship      — Create PR with detailed explanation
-</phases>
-
-<process>
-
-## Phase 1: Triage
-
-**Goal:** Understand the bug before touching any code.
-
-1. **Gather context:**
-   - If a GitHub issue was referenced, read the issue description, labels, and comments
-   - Identify the expected behavior vs actual behavior
-   - Note any error messages, stack traces, or reproduction steps provided
-
-2. **Reproduce:**
-   - Find the minimal reproduction path
-   - Identify the affected code paths (files, functions, lines)
-   - If the bug is intermittent, note the conditions that trigger it
-
-3. **Root cause analysis:**
-   - Trace the bug to its root cause (not just the symptom)
-   - Identify when the bug was introduced if possible (git blame/log)
-   - Assess blast radius: what else could be affected?
-
-4. **Produce:** Write a brief `TRIAGE.md` in the artifact directory with:
-   - Root cause explanation
-   - Reproduction steps
-   - Affected files/functions
-   - Proposed fix approach
-
-5. **Gate:** Present the triage findings and proposed fix to the user for confirmation.
-
-## Phase 2: Fix
-
-**Goal:** Implement a clean, tested fix.
-
-1. **Plan the fix:** Write a brief plan (1-3 tasks max)
-2. **Write the fix:** Implement the code change
-3. **Write tests:** Add or update tests that:
-   - Reproduce the original bug (test fails without fix)
-   - Verify the fix works
-   - Cover edge cases
-4. **Commit:** Atomic commit with message: `fix(<scope>): <description>`
-
-## Phase 3: Verify
-
-**Goal:** Ensure the fix doesn't break anything else.
-
-1. Run the project's full test suite
-2. Run the build (if applicable)
-3. Run the linter (if applicable)
-4. Check for regressions in related functionality
-5. If any failures, fix them before proceeding
-
-## Phase 4: Ship
-
-**Goal:** Create a well-documented PR.
-
-1. Ensure all changes are committed on the workflow branch
-2. Build the PR body:
-   - Link to the original issue (if applicable)
-   - Explain the root cause
-   - Describe the fix approach
-   - List the test coverage added
-3. Present the PR details to the user for review
-4. Create the PR via `gh pr create` (with user approval)
-
-</process>

package/src/resources/extensions/gsd/workflow-templates/dep-upgrade.md

@@ -1,74 +0,0 @@
-# Dependency Upgrade Workflow
-
-<template_meta>
-name: dep-upgrade
-version: 1
-requires_project: false
-artifact_dir: .gsd/workflows/upgrades/
-</template_meta>
-
-<purpose>
-Upgrade project dependencies safely. Assess breaking changes before upgrading,
-fix issues incrementally, and verify everything works. Handles both single-package
-upgrades and bulk dependency refresh.
-</purpose>
-
-<phases>
-1. assess  — Analyze what's outdated and what will break
-2. upgrade — Apply upgrades incrementally
-3. fix     — Resolve breaking changes
-4. verify  — Full test suite and build validation
-</phases>
-
-<process>
-
-## Phase 1: Assess
-
-**Goal:** Know what you're getting into before changing versions.
-
-1. **List outdated dependencies:** Run `npm outdated` / equivalent
-2. **For each target upgrade:**
-   - Read the changelog / release notes
-   - Identify breaking changes
-   - Check for known migration guides
-   - Assess impact on the codebase (grep for affected APIs)
-3. **Prioritize:** Which upgrades to do now, which to defer
-4. **Produce:** Write `ASSESSMENT.md` with:
-   - Dependency list with current → target versions
-   - Breaking changes per dependency
-   - Upgrade order (dependencies before dependents)
-   - Risk assessment
-
-5. **Gate:** Review assessment with user. Confirm upgrade scope.
-
-## Phase 2: Upgrade
-
-**Goal:** Apply version bumps incrementally.
-
-1. Upgrade one dependency (or one group of related dependencies) at a time
-2. Run tests after each upgrade
-3. Commit each upgrade: `chore(deps): upgrade <package> to <version>`
-4. If tests fail, move to Phase 3 for that dependency before continuing
-
-## Phase 3: Fix
-
-**Goal:** Resolve any breaking changes from upgrades.
-
-1. Fix API changes, type errors, deprecations
-2. Update configuration if needed
-3. Commit fixes separately from the upgrade: `fix(deps): adapt to <package> v<version> changes`
-
-## Phase 4: Verify
-
-**Goal:** Ensure everything works together.
-
-1. Run the full test suite
-2. Run the build
-3. Run the linter
-4. Check for deprecation warnings in output
-5. **Produce:** Write `SUMMARY.md` with:
-   - Dependencies upgraded (from → to)
-   - Breaking changes encountered and how they were resolved
-   - Any deferred upgrades and why
-
-</process>