gsd-pi 2.59.0-dev.3de3832 → 2.59.0-dev.d77b3dd

package/src/resources/extensions/gsd/tests/stop-backtrack.test.ts

@@ -0,0 +1,216 @@
+/**
+ * Unit tests for stop/backtrack capture classifications and milestone regression (#3487).
+ *
+ * Tests:
+ * - "stop" and "backtrack" are valid classification types
+ * - loadStopCaptures returns unexecuted stop+backtrack captures
+ * - loadBacktrackCaptures returns only backtrack captures
+ * - revertExecutorResolvedCaptures reverts silenced captures
+ * - executeBacktrack writes trigger and regression markers
+ * - readBacktrackTrigger parses trigger file
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, readFileSync, writeFileSync, rmSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { isClosedStatus } from "../status-guards.ts";
+import {
+  appendCapture,
+  loadAllCaptures,
+  loadStopCaptures,
+  loadBacktrackCaptures,
+  markCaptureResolved,
+  revertExecutorResolvedCaptures,
+  hasPendingCaptures,
+} from "../captures.ts";
+import {
+  executeBacktrack,
+  readBacktrackTrigger,
+} from "../triage-resolution.ts";
+
+function makeTempDir(prefix: string): string {
+  const dir = join(
+    tmpdir(),
+    `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  );
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function setupGsdDir(tmp: string): void {
+  mkdirSync(join(tmp, ".gsd"), { recursive: true });
+}
+
+// ─── Classification Types ─────────────────────────────────────────────────────
+
+test("stop is a valid classification", () => {
+  const tmp = makeTempDir("stop-class");
+  setupGsdDir(tmp);
+  const id = appendCapture(tmp, "stop running immediately");
+  markCaptureResolved(tmp, id, "stop", "Halt auto-mode", "User said stop", "M005");
+  const all = loadAllCaptures(tmp);
+  const cap = all.find(c => c.id === id);
+  assert.equal(cap?.classification, "stop");
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+test("backtrack is a valid classification", () => {
+  const tmp = makeTempDir("bt-class");
+  setupGsdDir(tmp);
+  const id = appendCapture(tmp, "restart from M003");
+  markCaptureResolved(tmp, id, "backtrack", "Backtrack to M003", "User wants to restart", "M005");
+  const all = loadAllCaptures(tmp);
+  const cap = all.find(c => c.id === id);
+  assert.equal(cap?.classification, "backtrack");
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+// ─── loadStopCaptures ─────────────────────────────────────────────────────────
+
+test("loadStopCaptures returns unexecuted stop and backtrack captures", () => {
+  const tmp = makeTempDir("load-stop");
+  setupGsdDir(tmp);
+  const stopId = appendCapture(tmp, "halt execution");
+  const btId = appendCapture(tmp, "go back to M003");
+  const noteId = appendCapture(tmp, "just a note");
+  markCaptureResolved(tmp, stopId, "stop", "Halt", "User stop", "M005");
+  markCaptureResolved(tmp, btId, "backtrack", "Backtrack to M003", "User backtrack", "M005");
+  markCaptureResolved(tmp, noteId, "note", "Info only", "Not actionable", "M005");
+
+  const stops = loadStopCaptures(tmp);
+  assert.equal(stops.length, 2);
+  assert.ok(stops.some(c => c.classification === "stop"));
+  assert.ok(stops.some(c => c.classification === "backtrack"));
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+test("loadBacktrackCaptures returns only backtrack captures", () => {
+  const tmp = makeTempDir("load-bt");
+  setupGsdDir(tmp);
+  const stopId = appendCapture(tmp, "halt execution");
+  const btId = appendCapture(tmp, "go back to M003");
+  markCaptureResolved(tmp, stopId, "stop", "Halt", "User stop", "M005");
+  markCaptureResolved(tmp, btId, "backtrack", "Backtrack to M003", "User backtrack", "M005");
+
+  const bts = loadBacktrackCaptures(tmp);
+  assert.equal(bts.length, 1);
+  assert.equal(bts[0].classification, "backtrack");
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+// ─── revertExecutorResolvedCaptures ───────────────────────────────────────────
+
+test("revertExecutorResolvedCaptures reverts captures resolved without classification", () => {
+  const tmp = makeTempDir("revert-exec");
+  setupGsdDir(tmp);
+  const id = appendCapture(tmp, "stop everything");
+
+  // Simulate an executor writing Status: resolved directly (no classification)
+  const capPath = join(tmp, ".gsd", "CAPTURES.md");
+  let content = readFileSync(capPath, "utf-8");
+  content = content.replace("**Status:** pending", "**Status:** resolved");
+  writeFileSync(capPath, content, "utf-8");
+
+  // Verify it's now "resolved" without classification
+  assert.equal(hasPendingCaptures(tmp), false);
+
+  // Revert should detect and fix it
+  const reverted = revertExecutorResolvedCaptures(tmp);
+  assert.equal(reverted, 1);
+
+  // Should be pending again
+  assert.equal(hasPendingCaptures(tmp), true);
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+test("revertExecutorResolvedCaptures does NOT revert properly triaged captures", () => {
+  const tmp = makeTempDir("revert-skip");
+  setupGsdDir(tmp);
+  const id = appendCapture(tmp, "restart from M003");
+  markCaptureResolved(tmp, id, "backtrack", "Backtrack to M003", "User wants restart", "M005");
+
+  // This capture was properly triaged — should NOT be reverted
+  const reverted = revertExecutorResolvedCaptures(tmp);
+  assert.equal(reverted, 0);
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+// ─── executeBacktrack ─────────────────────────────────────────────────────────
+
+test("executeBacktrack writes trigger and regression markers", () => {
+  const tmp = makeTempDir("exec-bt");
+  setupGsdDir(tmp);
+
+  // Create target milestone directory
+  mkdirSync(join(tmp, ".gsd", "milestones", "M003"), { recursive: true });
+
+  const targetMid = executeBacktrack(tmp, "M005", {
+    id: "CAP-test123",
+    text: "restart from M003 — milestones after 2 failed",
+    timestamp: new Date().toISOString(),
+    status: "resolved",
+    classification: "backtrack",
+    resolution: "Backtrack to M003",
+    rationale: "User directive",
+  });
+
+  assert.equal(targetMid, "M003");
+
+  // Check trigger file exists
+  const triggerPath = join(tmp, ".gsd", "BACKTRACK-TRIGGER.md");
+  assert.ok(existsSync(triggerPath));
+  const triggerContent = readFileSync(triggerPath, "utf-8");
+  assert.ok(triggerContent.includes("M005"));
+  assert.ok(triggerContent.includes("M003"));
+
+  // Check regression marker exists on target milestone
+  const regressionPath = join(tmp, ".gsd", "milestones", "M003", "M003-REGRESSION.md");
+  assert.ok(existsSync(regressionPath));
+  const regressionContent = readFileSync(regressionPath, "utf-8");
+  assert.ok(regressionContent.includes("M005"));
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+// ─── readBacktrackTrigger ─────────────────────────────────────────────────────
+
+test("readBacktrackTrigger parses trigger file", () => {
+  const tmp = makeTempDir("read-bt");
+  setupGsdDir(tmp);
+  mkdirSync(join(tmp, ".gsd", "milestones", "M003"), { recursive: true });
+
+  executeBacktrack(tmp, "M005", {
+    id: "CAP-abc",
+    text: "go back to M003",
+    timestamp: new Date().toISOString(),
+    status: "resolved",
+    classification: "backtrack",
+    resolution: "Backtrack to M003",
+    rationale: "Regression",
+  });
+
+  const trigger = readBacktrackTrigger(tmp);
+  assert.ok(trigger);
+  assert.equal(trigger.target, "M003");
+  assert.equal(trigger.from, "M005");
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+test("readBacktrackTrigger returns null when no trigger exists", () => {
+  const tmp = makeTempDir("no-bt");
+  setupGsdDir(tmp);
+  const trigger = readBacktrackTrigger(tmp);
+  assert.equal(trigger, null);
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+// ─── Slice Skip Status (#3477) ──────────────────────────────────────────────
+
+test("isClosedStatus treats 'skipped' as closed", () => {
+  assert.equal(isClosedStatus("skipped"), true);
+  assert.equal(isClosedStatus("complete"), true);
+  assert.equal(isClosedStatus("done"), true);
+  assert.equal(isClosedStatus("pending"), false);
+  assert.equal(isClosedStatus("active"), false);
+});

package/src/resources/extensions/gsd/tests/tool-naming.test.ts

@@ -45,7 +45,7 @@ console.log('\n── Tool naming: registration count ──');
 const pi = makeMockPi();
 registerDbTools(pi);
 
-assert.deepStrictEqual(pi.tools.length, 29, 'Should register exactly 29 tools (14 canonical + 14 aliases + 1 gate tool)');
+assert.deepStrictEqual(pi.tools.length, 30, 'Should register exactly 30 tools (14 canonical + 14 aliases + 1 gate tool + 1 gsd_skip_slice)');
 
 // ─── Both names exist for each pair ──────────────────────────────────────────
 

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}` : ""}`;

package/src/resources/skills/btw/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: btw
+description: Ask a quick side question about your current work without derailing the main task. Answers from existing conversation context only — no tool calls, no file reads, single concise response. Use when you need a fast answer from what is already in this session.
+---
+
+<objective>
+Answer a quick side question using only what is already present in the current conversation context. Do not read files, run commands, search, or use any tools. Give a single, concise response and return focus to the main work.
+</objective>
+
+<behavior>
+**This is a side question, not a task.**
+
+- Answer only from information already in the conversation (files read, decisions made, code seen, context established)
+- Do NOT use any tools — no Read, no Bash, no Grep, no Search
+- If the answer requires reading something new, say so briefly and suggest the user ask as a normal prompt instead
+- Keep the response short and direct — one to a few sentences unless the question genuinely needs more
+- Do not summarize the main work, ask follow-up questions, or offer to do anything else
+- After answering, stop — do not prompt for next steps
+</behavior>
+
+<quick_start>
+Parse the argument after `/btw` as the question. Answer it directly from context.
+
+If no argument is provided, ask: "What did you want to know?"
+
+If the question cannot be answered from current context (requires reading a file, running a command, or information not yet in the session), respond with:
+"I'd need to [read X / run Y / look up Z] to answer that — ask it as a normal prompt when you're ready."
+</quick_start>
+
+<examples>
+**Good uses of /btw:**
+- `/btw what was the name of that config file again?` → answers from files already read in session
+- `/btw which branch are we on?` → answers from git context already established
+- `/btw did we already handle the null case in that function?` → answers from code already reviewed
+- `/btw what model does this use?` → answers from code or config already in context
+
+**Not a good fit for /btw (suggest normal prompt):**
+- Questions requiring reading a file not yet seen
+- Questions requiring running a command
+- Questions needing a multi-step answer or follow-up
+- Starting a new task or changing direction
+</examples>