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

package/src/resources/extensions/gsd/preferences-types.ts

@@ -21,6 +21,13 @@ import type {
   GateEvaluationConfig,
 } from "./types.js";
 import type { DynamicRoutingConfig } from "./model-router.js";
+
+export interface ContextManagementConfig {
+  observation_masking?: boolean;          // default: true
+  observation_mask_turns?: number;        // default: 8, range: 1-50
+  compaction_threshold_percent?: number;  // default: 0.70, range: 0.5-0.95
+  tool_result_max_chars?: number;         // default: 800, range: 200-10000
+}
 import type { GitHubSyncConfig } from "../github-sync/types.js";
 
 // ─── Workflow Modes ──────────────────────────────────────────────────────────
@@ -94,6 +101,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "forensics_dedup",
   "show_token_cost",
   "stale_commit_threshold_minutes",
+  "context_management",
   "experimental",
 ]);
 
@@ -227,6 +235,7 @@ export interface GSDPreferences {
   post_unit_hooks?: PostUnitHookConfig[];
   pre_dispatch_hooks?: PreDispatchHookConfig[];
   dynamic_routing?: DynamicRoutingConfig;
+  context_management?: ContextManagementConfig;
   token_profile?: TokenProfile;
   phases?: PhaseSkipPreferences;
   auto_visualize?: boolean;

package/src/resources/extensions/gsd/preferences-validation.ts

@@ -428,6 +428,10 @@ export function validatePreferences(preferences: GSDPreferences): {
         if (typeof dr.hooks === "boolean") validDr.hooks = dr.hooks;
         else errors.push("dynamic_routing.hooks must be a boolean");
       }
+      if (dr.capability_routing !== undefined) {
+        if (typeof dr.capability_routing === "boolean") validDr.capability_routing = dr.capability_routing;
+        else errors.push("dynamic_routing.capability_routing must be a boolean");
+      }
       if (dr.tier_models !== undefined) {
         if (typeof dr.tier_models === "object" && dr.tier_models !== null) {
           const tm = dr.tier_models as Record<string, unknown>;
@@ -452,6 +456,40 @@ export function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
+  // ─── Context Management ──────────────────────────────────────────────
+  if (preferences.context_management !== undefined) {
+    if (typeof preferences.context_management === "object" && preferences.context_management !== null) {
+      const cm = preferences.context_management as unknown as Record<string, unknown>;
+      const validCm: Record<string, unknown> = {};
+
+      if (cm.observation_masking !== undefined) {
+        if (typeof cm.observation_masking === "boolean") validCm.observation_masking = cm.observation_masking;
+        else errors.push("context_management.observation_masking must be a boolean");
+      }
+      if (cm.observation_mask_turns !== undefined) {
+        const turns = cm.observation_mask_turns;
+        if (typeof turns === "number" && turns >= 1 && turns <= 50) validCm.observation_mask_turns = turns;
+        else errors.push("context_management.observation_mask_turns must be a number between 1 and 50");
+      }
+      if (cm.compaction_threshold_percent !== undefined) {
+        const pct = cm.compaction_threshold_percent;
+        if (typeof pct === "number" && pct >= 0.5 && pct <= 0.95) validCm.compaction_threshold_percent = pct;
+        else errors.push("context_management.compaction_threshold_percent must be a number between 0.5 and 0.95");
+      }
+      if (cm.tool_result_max_chars !== undefined) {
+        const chars = cm.tool_result_max_chars;
+        if (typeof chars === "number" && chars >= 200 && chars <= 10000) validCm.tool_result_max_chars = chars;
+        else errors.push("context_management.tool_result_max_chars must be a number between 200 and 10000");
+      }
+
+      if (Object.keys(validCm).length > 0) {
+        validated.context_management = validCm as any;
+      }
+    } else {
+      errors.push("context_management must be an object");
+    }
+  }
+
   // ─── Parallel Config ────────────────────────────────────────────────────
   if (preferences.parallel && typeof preferences.parallel === "object") {
     const p = preferences.parallel as unknown as Record<string, unknown>;

package/src/resources/extensions/gsd/prompts/execute-task.md

@@ -12,6 +12,8 @@ A researcher explored the codebase and a planner decomposed the work — you are
 
 {{runtimeContext}}
 
+{{phaseAnchorSection}}
+
 {{resumeSection}}
 
 {{carryForwardSection}}

package/src/resources/extensions/gsd/prompts/rethink.md

@@ -45,6 +45,13 @@ reason: "<reason>"
 ### Unpark a milestone
 Remove the `{ID}-PARKED.md` file from the milestone directory to reactivate it.
 
+### Skip a slice
+Mark a slice as skipped so auto-mode advances past it without executing. Use the `gsd_skip_slice` tool:
+```
+gsd_skip_slice({ milestone_id: "M003", slice_id: "S02", reason: "Descoped — feature moved to M005" })
+```
+Skipped slices are treated as closed by the state machine (like "complete" but distinct). Use when a slice is no longer needed or has been superseded. The slice data is preserved for reference.
+
 ### Discard a milestone
 **Permanently** delete a milestone directory and prune it from QUEUE-ORDER.json. **Always confirm with the user before discarding.** Warn explicitly if the milestone has completed work.
 

package/src/resources/extensions/gsd/prompts/triage-captures.md

@@ -20,6 +20,8 @@ The user captured thoughts during execution using `/gsd capture`. Your job is to
 
 For each capture, classify it as one of:
 
+- **stop**: User directive to halt auto-mode immediately. Use when the user says "stop", "halt", "abort", "don't continue", "pause", or otherwise wants execution to cease. Auto-mode will pause after the current unit completes. Examples: "stop running", "halt execution", "don't continue".
+- **backtrack**: User directive to abandon the current milestone and return to a previous one. The user believes earlier milestones missed critical features or need rework. Include the target milestone ID (e.g., M003) in the Resolution field. Auto-mode will pause and write a regression marker. Examples: "restart from M003", "go back to milestone 3", "M004 and M005 failed, restart from M003".
 - **quick-task**: Small, self-contained, no downstream impact. Can be done in minutes without modifying the plan. Examples: fix a typo, add a missing import, tweak a config value.
 - **inject**: Belongs in the current slice but wasn't planned. Needs a new task added to the slice plan. Examples: add error handling to a module being built, add a missing test case for current work.
 - **defer**: Belongs in a future slice or milestone. Not urgent for current work. Examples: performance optimization, feature that depends on unbuilt infrastructure, nice-to-have enhancement.
@@ -28,10 +30,12 @@ For each capture, classify it as one of:
 
 ## Decision Guidelines
 
+- **ALWAYS classify as stop** when the user explicitly says "stop", "halt", "abort", or "don't continue". Never shoe-horn a stop directive into "replan" or "note".
+- **ALWAYS classify as backtrack** when the user references returning to a previous milestone, restarting from an earlier point, or abandoning current milestone work. Include the target milestone ID in the Resolution field (e.g., "Backtrack to M003").
 - Prefer **quick-task** when the work is clearly small and self-contained.
 - Prefer **inject** over **replan** when only a new task is needed, not rewriting existing ones.
 - Prefer **defer** over **inject** when the work doesn't belong in the current slice's scope.
-- Use **replan** only when remaining incomplete tasks need to change — not just for adding work.
+- Use **replan** only when remaining incomplete tasks in the *current slice* need to change — not for cross-milestone issues.
 - Use **note** for observations that don't require action.
 - When unsure between quick-task and inject, consider: will this take more than 10 minutes? If yes, inject.
 
@@ -46,6 +50,7 @@ For each capture, classify it as one of:
    - If applicable, which files would be affected
    
    For captures classified as **note** or **defer**, auto-confirm without asking — these are low-impact.
+   For captures classified as **stop** or **backtrack**, auto-confirm without asking — these are urgent user directives that must be honored immediately.
    For captures classified as **quick-task**, **inject**, or **replan**, ask the user to confirm or choose a different classification.
 
 3. **Update** `.gsd/CAPTURES.md` — for each capture, update its section with the confirmed classification:

package/src/resources/extensions/gsd/rethink.ts

@@ -112,8 +112,11 @@ function buildRethinkData(
     if (dbAvailable && status !== "complete") {
       const slices = getMilestoneSlices(mid);
       if (slices.length > 0) {
-        const done = slices.filter(s => s.status === "complete").length;
-        sliceInfo = `${done}/${slices.length} complete`;
+        const done = slices.filter(s => s.status === "complete" || s.status === "done").length;
+        const skipped = slices.filter(s => s.status === "skipped").length;
+        sliceInfo = skipped > 0
+          ? `${done}/${slices.length} complete, ${skipped} skipped`
+          : `${done}/${slices.length} complete`;
       }
     }
 

package/src/resources/extensions/gsd/state.ts

@@ -295,7 +295,7 @@ function extractContextTitle(content: string | null, fallback: string): string {
  * Helper: check if a DB status counts as "done" (handles K002 ambiguity).
  */
 function isStatusDone(status: string): boolean {
-  return status === 'complete' || status === 'done';
+  return status === 'complete' || status === 'done' || status === 'skipped';
 }
 
 /**

package/src/resources/extensions/gsd/status-guards.ts

@@ -1,13 +1,14 @@
 /**
  * Status predicates for GSD state-machine guards.
  *
- * The DB stores status as free-form strings. Two values indicate
- * "closed": "complete" (canonical) and "done" (legacy / alias).
+ * The DB stores status as free-form strings. Three values indicate
+ * "closed": "complete" (canonical), "done" (legacy / alias), and
+ * "skipped" (user-directed skip via rethink or backtrack).
  * Every inline `status === "complete" || status === "done"` should
  * use isClosedStatus() instead.
  */
 
 /** Returns true when a milestone, slice, or task status indicates closure. */
 export function isClosedStatus(status: string): boolean {
-  return status === "complete" || status === "done";
+  return status === "complete" || status === "done" || status === "skipped";
 }

package/src/resources/extensions/gsd/tests/context-masker.test.ts

@@ -0,0 +1,122 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { createObservationMask } from "../context-masker.js";
+
+// These helpers produce messages in the pi-ai LLM payload format
+// (post-convertToLlm, pre-provider), which is what before_provider_request sees.
+
+function userMsg(content: string) {
+  return { role: "user", content: [{ type: "text", text: content }] };
+}
+
+function assistantMsg(content: string) {
+  return { role: "assistant", content: [{ type: "text", text: content }] };
+}
+
+/** toolResult in pi-ai format: role "toolResult", content as TextContent[] */
+function toolResult(text: string) {
+  return { role: "toolResult", content: [{ type: "text", text }], toolCallId: "toolu_test", toolName: "Read", isError: false };
+}
+
+/** bashExecution after convertToLlm: becomes a user message with "Ran `cmd`" prefix */
+function bashResult(text: string) {
+  return { role: "user", content: [{ type: "text", text: `Ran \`echo test\`\n\`\`\`\n${text}\n\`\`\`` }] };
+}
+
+const MASK_TEXT = "[result masked — within summarized history]";
+
+test("masks nothing when message count is within keepRecentTurns", () => {
+  const mask = createObservationMask(8);
+  const messages = [
+    userMsg("hello"),
+    assistantMsg("hi"),
+    toolResult("file contents"),
+  ];
+  const result = mask(messages as any);
+  assert.equal(result.length, 3);
+  assert.deepEqual((result[2].content as any)[0].text, "file contents");
+});
+
+test("masks tool results older than keepRecentTurns", () => {
+  const mask = createObservationMask(2);
+  const messages = [
+    userMsg("turn 1"),
+    toolResult("old tool output"),
+    assistantMsg("response 1"),
+    userMsg("turn 2"),
+    toolResult("newer tool output"),
+    assistantMsg("response 2"),
+    userMsg("turn 3"),
+    toolResult("newest tool output"),
+    assistantMsg("response 3"),
+  ];
+  const result = mask(messages as any);
+  // Old tool result (before boundary) should be masked
+  assert.equal((result[1].content as any)[0].text, MASK_TEXT);
+  // Recent tool results (within keep window) should be preserved
+  assert.equal((result[4].content as any)[0].text, "newer tool output");
+  assert.equal((result[7].content as any)[0].text, "newest tool output");
+});
+
+test("never masks assistant messages", () => {
+  const mask = createObservationMask(1);
+  const messages = [
+    userMsg("turn 1"),
+    assistantMsg("old reasoning"),
+    userMsg("turn 2"),
+    assistantMsg("new reasoning"),
+  ];
+  const result = mask(messages as any);
+  assert.equal((result[1].content as any)[0].text, "old reasoning");
+  assert.equal((result[3].content as any)[0].text, "new reasoning");
+});
+
+test("never masks user messages", () => {
+  const mask = createObservationMask(1);
+  const messages = [
+    userMsg("old user message"),
+    assistantMsg("response"),
+    userMsg("new user message"),
+    assistantMsg("response"),
+  ];
+  const result = mask(messages as any);
+  assert.equal((result[0].content as any)[0].text, "old user message");
+});
+
+test("masks bash result user messages", () => {
+  const mask = createObservationMask(1);
+  const messages = [
+    userMsg("turn 1"),
+    bashResult("huge log output"),
+    assistantMsg("response 1"),
+    userMsg("turn 2"),
+    assistantMsg("response 2"),
+  ];
+  const result = mask(messages as any);
+  assert.equal((result[1].content as any)[0].text, MASK_TEXT);
+});
+
+test("returns same array length", () => {
+  const mask = createObservationMask(1);
+  const messages = [
+    userMsg("a"), toolResult("b"), assistantMsg("c"),
+    userMsg("d"), toolResult("e"), assistantMsg("f"),
+  ];
+  const result = mask(messages as any);
+  assert.equal(result.length, messages.length);
+});
+
+test("masks toolResult by role, not by type field", () => {
+  const mask = createObservationMask(1);
+  const messages = [
+    userMsg("turn 1"),
+    // This is the actual pi-ai format: role "toolResult", no type field
+    { role: "toolResult", content: [{ type: "text", text: "old result" }], toolCallId: "t1", toolName: "Read", isError: false },
+    assistantMsg("response 1"),
+    userMsg("turn 2"),
+    assistantMsg("response 2"),
+  ];
+  const result = mask(messages as any);
+  assert.equal((result[1].content as any)[0].text, MASK_TEXT);
+});

package/src/resources/extensions/gsd/tests/model-router.test.ts

@@ -5,8 +5,11 @@ import {
   resolveModelForComplexity,
   escalateTier,
   defaultRoutingConfig,
+  scoreModel,
+  computeTaskRequirements,
+  MODEL_CAPABILITY_PROFILES,
 } from "../model-router.js";
-import type { DynamicRoutingConfig, RoutingDecision } from "../model-router.js";
+import type { DynamicRoutingConfig, RoutingDecision, ModelCapabilities } from "../model-router.js";
 import type { ClassificationResult } from "../complexity-classifier.js";
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
@@ -206,6 +209,89 @@ test("#2192: known model is still downgraded normally", () => {
   assert.notEqual(result.modelId, "claude-opus-4-6");
 });
 
+// ─── Capability Scoring (ADR-004 Phase 2) ───────────────────────────────────
+
+test("defaultRoutingConfig includes capability_routing: false", () => {
+  const config = defaultRoutingConfig();
+  assert.equal(config.capability_routing, false);
+});
+
+test("scoreModel computes weighted average of capability × requirement", () => {
+  const caps: ModelCapabilities = {
+    coding: 90, debugging: 80, research: 70,
+    reasoning: 85, speed: 50, longContext: 60, instruction: 75,
+  };
+  const reqs = { coding: 0.9, reasoning: 0.5 };
+  const score = scoreModel(caps, reqs);
+  // Expected: (0.9*90 + 0.5*85) / (0.9 + 0.5) = (81 + 42.5) / 1.4 = 88.21...
+  assert.ok(Math.abs(score - 88.21) < 0.1, `score ${score} should be ~88.21`);
+});
+
+test("scoreModel returns 50 for empty requirements", () => {
+  const caps: ModelCapabilities = {
+    coding: 90, debugging: 80, research: 70,
+    reasoning: 85, speed: 50, longContext: 60, instruction: 75,
+  };
+  const score = scoreModel(caps, {});
+  assert.equal(score, 50);
+});
+
+test("computeTaskRequirements returns base vector for known unit type", () => {
+  const reqs = computeTaskRequirements("execute-task");
+  assert.ok(reqs.coding !== undefined && reqs.coding > 0);
+});
+
+test("computeTaskRequirements boosts instruction for docs-tagged tasks", () => {
+  const reqs = computeTaskRequirements("execute-task", { tags: ["docs"] });
+  assert.ok((reqs.instruction ?? 0) >= 0.8);
+  assert.ok((reqs.coding ?? 1) <= 0.4);
+});
+
+test("computeTaskRequirements returns generic vector for unknown unit type", () => {
+  const reqs = computeTaskRequirements("unknown-unit");
+  assert.ok(reqs.reasoning !== undefined);
+});
+
+test("resolveModelForComplexity uses capability scoring when enabled", () => {
+  const config: DynamicRoutingConfig = {
+    ...defaultRoutingConfig(),
+    enabled: true,
+    capability_routing: true,
+  };
+  const result = resolveModelForComplexity(
+    makeClassification("light"),
+    { primary: "claude-opus-4-6", fallbacks: [] },
+    config,
+    ["claude-opus-4-6", "claude-haiku-4-5", "gpt-4o-mini"],
+    "execute-task",
+  );
+  assert.equal(result.wasDowngraded, true);
+  assert.equal(result.selectionMethod, "capability-scored");
+});
+
+test("resolveModelForComplexity falls back to tier-only when capability_routing is false", () => {
+  const config: DynamicRoutingConfig = {
+    ...defaultRoutingConfig(),
+    enabled: true,
+    capability_routing: false,
+  };
+  const result = resolveModelForComplexity(
+    makeClassification("light"),
+    { primary: "claude-opus-4-6", fallbacks: [] },
+    config,
+    ["claude-opus-4-6", "claude-haiku-4-5", "gpt-4o-mini"],
+  );
+  assert.equal(result.wasDowngraded, true);
+  assert.ok(!result.selectionMethod || result.selectionMethod === "tier-only");
+});
+
+test("MODEL_CAPABILITY_PROFILES has entries for core models", () => {
+  const profiledModels = Object.keys(MODEL_CAPABILITY_PROFILES);
+  assert.ok(profiledModels.length >= 9, `Expected ≥9 profiles, got ${profiledModels.length}`);
+  assert.ok(MODEL_CAPABILITY_PROFILES["claude-opus-4-6"]);
+  assert.ok(MODEL_CAPABILITY_PROFILES["claude-haiku-4-5"]);
+});
+
 // ─── #2885: openai-codex and modern OpenAI models in tier map ────────────────
 
 test("#2885: openai-codex light-tier models are recognized", () => {

package/src/resources/extensions/gsd/tests/phase-anchor.test.ts

@@ -0,0 +1,83 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { writePhaseAnchor, readPhaseAnchor, formatAnchorForPrompt } from "../phase-anchor.js";
+import type { PhaseAnchor } from "../phase-anchor.js";
+
+function makeTempBase(): string {
+  const tmp = mkdtempSync(join(tmpdir(), "gsd-anchor-test-"));
+  mkdirSync(join(tmp, ".gsd", "milestones", "M001", "anchors"), { recursive: true });
+  return tmp;
+}
+
+test("writePhaseAnchor creates anchor file in correct location", () => {
+  const base = makeTempBase();
+  try {
+    const anchor: PhaseAnchor = {
+      phase: "discuss",
+      milestoneId: "M001",
+      generatedAt: new Date().toISOString(),
+      intent: "Define authentication requirements",
+      decisions: ["Use JWT tokens", "Session expiry 24h"],
+      blockers: [],
+      nextSteps: ["Plan the implementation slices"],
+    };
+    writePhaseAnchor(base, "M001", anchor);
+    assert.ok(existsSync(join(base, ".gsd", "milestones", "M001", "anchors", "discuss.json")));
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("readPhaseAnchor returns written anchor", () => {
+  const base = makeTempBase();
+  try {
+    const anchor: PhaseAnchor = {
+      phase: "plan",
+      milestoneId: "M001",
+      generatedAt: new Date().toISOString(),
+      intent: "Break work into slices",
+      decisions: ["3 slices: auth, UI, tests"],
+      blockers: ["Need DB schema first"],
+      nextSteps: ["Execute S01"],
+    };
+    writePhaseAnchor(base, "M001", anchor);
+    const read = readPhaseAnchor(base, "M001", "plan");
+    assert.ok(read);
+    assert.equal(read!.intent, "Break work into slices");
+    assert.deepEqual(read!.decisions, ["3 slices: auth, UI, tests"]);
+    assert.deepEqual(read!.blockers, ["Need DB schema first"]);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("readPhaseAnchor returns null when no anchor exists", () => {
+  const base = makeTempBase();
+  try {
+    const read = readPhaseAnchor(base, "M001", "discuss");
+    assert.equal(read, null);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("formatAnchorForPrompt produces markdown block", () => {
+  const anchor: PhaseAnchor = {
+    phase: "discuss",
+    milestoneId: "M001",
+    generatedAt: "2026-04-03T00:00:00.000Z",
+    intent: "Define requirements",
+    decisions: ["Use JWT"],
+    blockers: [],
+    nextSteps: ["Plan slices"],
+  };
+  const md = formatAnchorForPrompt(anchor);
+  assert.ok(md.includes("## Handoff from discuss"));
+  assert.ok(md.includes("Define requirements"));
+  assert.ok(md.includes("Use JWT"));
+  assert.ok(md.includes("Plan slices"));
+});

package/src/resources/extensions/gsd/tests/status-guards.test.ts

@@ -13,6 +13,10 @@ test('isClosedStatus: "done" returns true', () => {
   assert.equal(isClosedStatus('done'), true);
 });
 
+test('isClosedStatus: "skipped" returns true', () => {
+  assert.equal(isClosedStatus('skipped'), true);
+});
+
 test('isClosedStatus: "pending" returns false', () => {
   assert.equal(isClosedStatus('pending'), false);
 });