gsd-pi 2.59.0-dev.023bd39 → 2.59.0-dev.d77b3dd

package/src/resources/extensions/gsd/triage-resolution.ts

@@ -10,7 +10,7 @@
  * Also provides detectFileOverlap() for surfacing downstream impact on quick tasks.
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { createRequire } from "node:module";
 import { gsdRoot, milestonesDir } from "./paths.js";
@@ -129,6 +129,129 @@ export function executeReplan(
   }
 }
 
+// ─── Backtrack (Milestone Regression) ────────────────────────────────────────
+
+/**
+ * Execute a backtrack directive — user wants to abandon current milestone
+ * and return to a previous one (milestone regression).
+ *
+ * Writes a BACKTRACK-TRIGGER.md marker at `.gsd/BACKTRACK-TRIGGER.md` with
+ * the target milestone, reason, and timestamp. The state machine (deriveState)
+ * detects this and transitions the project to the target milestone, resetting
+ * its slices to allow re-planning.
+ *
+ * Returns the extracted target milestone ID, or null if extraction failed.
+ */
+export function executeBacktrack(
+  basePath: string,
+  currentMilestoneId: string,
+  capture: CaptureEntry,
+): string | null {
+  try {
+    // Extract target milestone from capture text or resolution
+    const targetMatch = (capture.resolution ?? capture.text)
+      .match(/\b(M\d{3}(?:-[a-z0-9]{6})?)\b/);
+    const targetMilestoneId = targetMatch?.[1] ?? null;
+
+    const ts = new Date().toISOString();
+    const triggerPath = join(gsdRoot(basePath), "BACKTRACK-TRIGGER.md");
+    const content = [
+      `# Backtrack Trigger`,
+      ``,
+      `**Source:** Capture ${capture.id}`,
+      `**Capture:** ${capture.text}`,
+      `**Rationale:** ${capture.rationale ?? "User-initiated milestone backtrack"}`,
+      `**From:** ${currentMilestoneId}`,
+      `**Target:** ${targetMilestoneId ?? "(user to specify)"}`,
+      `**Triggered:** ${ts}`,
+      ``,
+      `Auto-mode was paused by this backtrack directive. The user directed`,
+      `that the current milestone (${currentMilestoneId}) be abandoned and work`,
+      `should return to ${targetMilestoneId ?? "a previous milestone"}.`,
+      ``,
+      `## Recovery Steps`,
+      ``,
+      `1. Review what went wrong in ${currentMilestoneId}`,
+      `2. Identify missing features/requirements from the target milestone`,
+      `3. Resume auto-mode — the state machine will re-enter discussion for the target`,
+    ].join("\n");
+
+    writeFileSync(triggerPath, content, "utf-8");
+
+    // If we have a valid target, also reset that milestone's completion status
+    // so deriveState() will re-enter it as the active milestone.
+    if (targetMilestoneId) {
+      try {
+        const targetDir = join(milestonesDir(basePath), targetMilestoneId);
+        if (existsSync(targetDir)) {
+          // Write a regression marker so the state machine knows this milestone
+          // needs re-discussion, not just re-execution
+          const regressionPath = join(targetDir, `${targetMilestoneId}-REGRESSION.md`);
+          writeFileSync(regressionPath, [
+            `# Milestone Regression`,
+            ``,
+            `**From:** ${currentMilestoneId}`,
+            `**Reason:** ${capture.text}`,
+            `**Triggered:** ${ts}`,
+            ``,
+            `This milestone is being revisited because downstream milestone`,
+            `${currentMilestoneId} failed or missed critical features that should`,
+            `have been part of this milestone's scope.`,
+            ``,
+            `The discuss phase should re-evaluate requirements and identify gaps.`,
+          ].join("\n"), "utf-8");
+        }
+      } catch { /* best-effort */ }
+    }
+
+    return targetMilestoneId;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read the backtrack trigger file if it exists.
+ * Returns the parsed target milestone and metadata, or null.
+ */
+export function readBacktrackTrigger(basePath: string): {
+  target: string | null;
+  from: string | null;
+  capture: string;
+  triggeredAt: string;
+} | null {
+  const triggerPath = join(gsdRoot(basePath), "BACKTRACK-TRIGGER.md");
+  if (!existsSync(triggerPath)) return null;
+
+  try {
+    const content = readFileSync(triggerPath, "utf-8");
+    const target = content.match(/\*\*Target:\*\*\s*(.+)/)?.[1]?.trim() ?? null;
+    const from = content.match(/\*\*From:\*\*\s*(.+)/)?.[1]?.trim() ?? null;
+    const capture = content.match(/\*\*Capture:\*\*\s*(.+)/)?.[1]?.trim() ?? "";
+    const triggeredAt = content.match(/\*\*Triggered:\*\*\s*(.+)/)?.[1]?.trim() ?? "";
+    return {
+      target: target === "(user to specify)" ? null : target,
+      from,
+      capture,
+      triggeredAt,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Remove the backtrack trigger after it has been processed.
+ */
+export function clearBacktrackTrigger(basePath: string): void {
+  const triggerPath = join(gsdRoot(basePath), "BACKTRACK-TRIGGER.md");
+  try {
+    if (existsSync(triggerPath)) {
+      unlinkSync(triggerPath);
+    }
+  } catch { /* best-effort */ }
+}
+
 // ─── File Overlap Detection ───────────────────────────────────────────────────
 
 /**
@@ -298,6 +421,10 @@ export interface TriageExecutionResult {
   deferredMilestones: number;
   /** Captures classified as quick-task that need dispatch */
   quickTasks: CaptureEntry[];
+  /** Number of stop directives (will pause auto-mode via guard) */
+  stopped: number;
+  /** Backtrack captures (will trigger milestone regression via guard) */
+  backtracks: CaptureEntry[];
   /** Details of each action taken, for logging */
   actions: string[];
 }
@@ -326,6 +453,8 @@ export function executeTriageResolutions(
     replanned: 0,
     deferredMilestones: 0,
     quickTasks: [],
+    stopped: 0,
+    backtracks: [],
     actions: [],
   };
 
@@ -409,5 +538,19 @@ export function executeTriageResolutions(
     }
   }
 
+  // Count stop/backtrack captures — these are handled by the pre-dispatch guard
+  // in runGuards(), not here. We just report them for logging purposes.
+  const allCaptures = loadAllCaptures(basePath);
+  for (const cap of allCaptures) {
+    if (cap.status !== "resolved" || cap.executed) continue;
+    if (cap.classification === "stop") {
+      result.stopped++;
+      result.actions.push(`Stop directive from ${cap.id}: "${cap.text}" — will pause on next dispatch`);
+    } else if (cap.classification === "backtrack") {
+      result.backtracks.push(cap);
+      result.actions.push(`Backtrack directive from ${cap.id}: "${cap.text}" — will trigger milestone regression on next dispatch`);
+    }
+  }
+
   return result;
 }

package/src/resources/extensions/gsd/triage-ui.ts

@@ -49,10 +49,18 @@ const CLASSIFICATION_LABELS: Record<Classification, { label: string; description
     label: "Note",
     description: "Informational only — no action needed.",
   },
+  "stop": {
+    label: "Stop",
+    description: "Halt auto-mode immediately — user directive to cease execution.",
+  },
+  "backtrack": {
+    label: "Backtrack",
+    description: "Abandon current milestone and return to a previous one.",
+  },
 };
 
 const ALL_CLASSIFICATIONS: Classification[] = [
-  "quick-task", "inject", "defer", "replan", "note",
+  "quick-task", "inject", "defer", "replan", "note", "stop", "backtrack",
 ];
 
 // ─── Public API ───────────────────────────────────────────────────────────────
@@ -83,8 +91,9 @@ export async function showTriageConfirmation(
     const capture = captureMap.get(result.captureId);
     if (!capture) continue;
 
-    // Auto-confirm note and defer — low-impact, no plan modification
-    if (result.classification === "note" || result.classification === "defer") {
+    // Auto-confirm note, defer, stop, and backtrack — low-impact or urgent directives
+    if (result.classification === "note" || result.classification === "defer"
+      || result.classification === "stop" || result.classification === "backtrack") {
       const resolution = result.classification === "note"
         ? "acknowledged as note"
         : `deferred${result.targetSlice ? ` to ${result.targetSlice}` : ""}`;