gsd-pi 2.16.0 → 2.18.0

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

@@ -1,9 +1,9 @@
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import { getAgentDir } from "@gsd/pi-coding-agent";
 import type { GitPreferences } from "./git-service.js";
-import type { PostUnitHookConfig, PreDispatchHookConfig, BudgetEnforcementMode, NotificationPreferences } from "./types.js";
+import type { PostUnitHookConfig, PreDispatchHookConfig, BudgetEnforcementMode, NotificationPreferences, TokenProfile, InlineLevel, PhaseSkipPreferences } from "./types.js";
 import { VALID_BRANCH_NAME } from "./git-service.js";
 
 const GLOBAL_PREFERENCES_PATH = join(homedir(), ".gsd", "preferences.md");
@@ -36,6 +36,8 @@ const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "git",
   "post_unit_hooks",
   "pre_dispatch_hooks",
+  "token_profile",
+  "phases",
 ]);
 
 export interface GSDSkillRule {
@@ -66,7 +68,9 @@ export interface GSDModelConfig {
   research?: string;
   planning?: string;
   execution?: string;
+  execution_simple?: string;
   completion?: string;
+  subagent?: string;
 }
 
 /**
@@ -77,7 +81,9 @@ export interface GSDModelConfigV2 {
   research?: string | GSDPhaseModelConfig;
   planning?: string | GSDPhaseModelConfig;
   execution?: string | GSDPhaseModelConfig;
+  execution_simple?: string | GSDPhaseModelConfig;
   completion?: string | GSDPhaseModelConfig;
+  subagent?: string | GSDPhaseModelConfig;
 }
 
 /** Normalized model selection with resolved fallbacks */
@@ -122,6 +128,8 @@ export interface GSDPreferences {
   git?: GitPreferences;
   post_unit_hooks?: PostUnitHookConfig[];
   pre_dispatch_hooks?: PreDispatchHookConfig[];
+  token_profile?: TokenProfile;
+  phases?: PhaseSkipPreferences;
 }
 
 export interface LoadedGSDPreferences {
@@ -631,11 +639,19 @@ export function resolveModelWithFallbacksForUnit(unitType: string): ResolvedMode
     case "execute-task":
       phaseConfig = m.execution;
       break;
+    case "execute-task-simple":
+      phaseConfig = m.execution_simple ?? m.execution;
+      break;
     case "complete-slice":
     case "run-uat":
       phaseConfig = m.completion;
       break;
     default:
+      // Subagent unit types (e.g., "subagent", "subagent/scout")
+      if (unitType === "subagent" || unitType.startsWith("subagent/")) {
+        phaseConfig = m.subagent;
+        break;
+      }
       return undefined;
   }
 
@@ -670,6 +686,73 @@ export function resolveAutoSupervisorConfig(): AutoSupervisorConfig {
   };
 }
 
+// ─── Token Profile Resolution ─────────────────────────────────────────────
+
+const VALID_TOKEN_PROFILES = new Set<TokenProfile>(["budget", "balanced", "quality"]);
+
+/**
+ * Resolve profile defaults for a given token profile tier.
+ * Returns a partial GSDPreferences that is used as the base layer —
+ * explicit user preferences always override these defaults.
+ */
+export function resolveProfileDefaults(profile: TokenProfile): Partial<GSDPreferences> {
+  switch (profile) {
+    case "budget":
+      return {
+        models: {
+          planning: "claude-sonnet-4-5-20250514",
+          execution: "claude-sonnet-4-5-20250514",
+          execution_simple: "claude-haiku-4-5-20250414",
+          completion: "claude-haiku-4-5-20250414",
+          subagent: "claude-haiku-4-5-20250414",
+        },
+        phases: {
+          skip_research: true,
+          skip_reassess: true,
+          skip_slice_research: true,
+        },
+      };
+    case "balanced":
+      return {
+        models: {
+          subagent: "claude-sonnet-4-5-20250514",
+        },
+        phases: {
+          skip_slice_research: true,
+        },
+      };
+    case "quality":
+      return {
+        models: {},
+        phases: {},
+      };
+  }
+}
+
+/**
+ * Resolve the effective token profile from preferences.
+ * Returns "balanced" when no profile is set (D046).
+ */
+export function resolveEffectiveProfile(): TokenProfile {
+  const prefs = loadEffectiveGSDPreferences();
+  const profile = prefs?.preferences.token_profile;
+  if (profile && VALID_TOKEN_PROFILES.has(profile)) return profile;
+  return "balanced";
+}
+
+/**
+ * Resolve the inline level from the active token profile.
+ * budget → minimal, balanced → standard, quality → full.
+ */
+export function resolveInlineLevel(): InlineLevel {
+  const profile = resolveEffectiveProfile();
+  switch (profile) {
+    case "budget": return "minimal";
+    case "balanced": return "standard";
+    case "quality": return "full";
+  }
+}
+
 function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPreferences {
   return {
     version: override.version ?? base.version,
@@ -697,6 +780,10 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr
       : undefined,
     post_unit_hooks: mergePostUnitHooks(base.post_unit_hooks, override.post_unit_hooks),
     pre_dispatch_hooks: mergePreDispatchHooks(base.pre_dispatch_hooks, override.pre_dispatch_hooks),
+    token_profile: override.token_profile ?? base.token_profile,
+    phases: (base.phases || override.phases)
+      ? { ...(base.phases ?? {}), ...(override.phases ?? {}) }
+      : undefined,
   };
 }
 
@@ -803,6 +890,36 @@ export function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
+  // ─── Token Profile ─────────────────────────────────────────────────
+  if (preferences.token_profile !== undefined) {
+    if (typeof preferences.token_profile === "string" && VALID_TOKEN_PROFILES.has(preferences.token_profile as TokenProfile)) {
+      validated.token_profile = preferences.token_profile as TokenProfile;
+    } else {
+      errors.push(`token_profile must be one of: budget, balanced, quality`);
+    }
+  }
+
+  // ─── Phase Skip Preferences ─────────────────────────────────────────
+  if (preferences.phases !== undefined) {
+    if (typeof preferences.phases === "object" && preferences.phases !== null) {
+      const validatedPhases: PhaseSkipPreferences = {};
+      const p = preferences.phases as Record<string, unknown>;
+      if (p.skip_research !== undefined) validatedPhases.skip_research = !!p.skip_research;
+      if (p.skip_reassess !== undefined) validatedPhases.skip_reassess = !!p.skip_reassess;
+      if (p.skip_slice_research !== undefined) validatedPhases.skip_slice_research = !!p.skip_slice_research;
+      // Warn on unknown phase keys
+      const knownPhaseKeys = new Set(["skip_research", "skip_reassess", "skip_slice_research"]);
+      for (const key of Object.keys(p)) {
+        if (!knownPhaseKeys.has(key)) {
+          warnings.push(`unknown phases key "${key}" — ignored`);
+        }
+      }
+      validated.phases = validatedPhases;
+    } else {
+      errors.push(`phases must be an object`);
+    }
+  }
+
   // ─── Context Pause Threshold ────────────────────────────────────────
   if (preferences.context_pause_threshold !== undefined) {
     const raw = preferences.context_pause_threshold;
@@ -1046,6 +1163,10 @@ export function validatePreferences(preferences: GSDPreferences): {
         errors.push("git.isolation must be one of: worktree, branch");
       }
     }
+    if (g.commit_docs !== undefined) {
+      if (typeof g.commit_docs === "boolean") git.commit_docs = g.commit_docs;
+      else errors.push("git.commit_docs must be a boolean");
+    }
     // Deprecated: merge_to_main is ignored (branchless architecture).
     if (g.merge_to_main !== undefined) {
       warnings.push("git.merge_to_main is deprecated — milestone-level merge is now always used. Remove this setting.");
@@ -1131,3 +1252,61 @@ export function resolvePreDispatchHooks(): PreDispatchHookConfig[] {
   return (prefs?.preferences.pre_dispatch_hooks ?? [])
     .filter(h => h.enabled !== false);
 }
+
+/**
+ * Validate a model ID string.
+ * Returns true if the ID looks like a valid model identifier.
+ */
+export function validateModelId(modelId: string): boolean {
+  if (!modelId || typeof modelId !== "string") return false;
+  const trimmed = modelId.trim();
+  if (trimmed.length === 0 || trimmed.length > 256) return false;
+  // Allow alphanumeric, hyphens, underscores, dots, slashes, colons
+  return /^[a-zA-Z0-9\-_./:]+$/.test(trimmed);
+}
+
+/**
+ * Update the models section of the global GSD preferences file.
+ * Performs a safe read-modify-write: reads current content, updates the models
+ * YAML block, and writes back. Creates the file if it doesn't exist.
+ */
+export function updatePreferencesModels(models: GSDModelConfigV2): void {
+  const prefsPath = getGlobalGSDPreferencesPath();
+
+  let content = "";
+  if (existsSync(prefsPath)) {
+    content = readFileSync(prefsPath, "utf-8");
+  }
+
+  // Build the new models block
+  const lines: string[] = ["models:"];
+  for (const [phase, value] of Object.entries(models)) {
+    if (typeof value === "string") {
+      lines.push(`  ${phase}: ${value}`);
+    } else if (value && typeof value === "object") {
+      const config = value as GSDPhaseModelConfig;
+      lines.push(`  ${phase}:`);
+      lines.push(`    model: ${config.model}`);
+      if (config.provider) {
+        lines.push(`    provider: ${config.provider}`);
+      }
+      if (config.fallbacks && config.fallbacks.length > 0) {
+        lines.push(`    fallbacks:`);
+        for (const fb of config.fallbacks) {
+          lines.push(`      - ${fb}`);
+        }
+      }
+    }
+  }
+  const modelsBlock = lines.join("\n");
+
+  // Replace existing models block or append
+  const modelsRegex = /^models:[\s\S]*?(?=\n[a-z_]|\n*$)/m;
+  if (modelsRegex.test(content)) {
+    content = content.replace(modelsRegex, modelsBlock);
+  } else {
+    content = content.trimEnd() + "\n\n" + modelsBlock + "\n";
+  }
+
+  writeFileSync(prefsPath, content, "utf-8");
+}

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

@@ -54,11 +54,12 @@ Then:
     - Don't fix symptoms. Understand *why* something fails before changing code. A test that passes after a change you don't understand is luck, not a fix.
 11. **Blocker discovery:** If execution reveals that the remaining slice plan is fundamentally invalid — not just a bug or minor deviation, but a plan-invalidating finding like a wrong API, missing capability, or architectural mismatch — set `blocker_discovered: true` in the task summary frontmatter and describe the blocker clearly in the summary narrative. Do NOT set `blocker_discovered: true` for ordinary debugging, minor deviations, or issues that can be fixed within the current task or the remaining plan. This flag triggers an automatic replan of the slice.
 12. If you made an architectural, pattern, library, or observability decision during this task that downstream work should know about, append it to `.gsd/DECISIONS.md` (use the **Decisions** output template from the inlined templates below if the file doesn't exist yet). Not every task produces decisions — only append when a meaningful choice was made.
-13. Use the **Task Summary** output template from the inlined templates below
-14. Write `{{taskSummaryPath}}`
-15. Mark {{taskId}} done in `{{planPath}}` (change `[ ]` to `[x]`)
-16. Do not commit manually — the system auto-commits your changes after this unit completes.
-17. Update `.gsd/STATE.md`
+13. If you discover a non-obvious rule, recurring gotcha, or useful pattern during execution, append it to `.gsd/KNOWLEDGE.md`. Only add entries that would save future agents from repeating your investigation. Don't add obvious things.
+14. Use the **Task Summary** output template from the inlined templates below
+15. Write `{{taskSummaryPath}}`
+16. Mark {{taskId}} done in `{{planPath}}` (change `[ ]` to `[x]`)
+17. Do not commit manually — the system auto-commits your changes after this unit completes.
+18. Update `.gsd/STATE.md`
 
 All work stays in your working directory: `{{workingDirectory}}`.
 

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

@@ -65,6 +65,7 @@ Titles live inside file content (headings, frontmatter), not in file or director
   PROJECT.md            (living doc - what the project is right now)
   REQUIREMENTS.md       (requirement contract - tracks active/validated/deferred/out-of-scope)
   DECISIONS.md          (append-only register of architectural and pattern decisions)
+  KNOWLEDGE.md          (append-only register of project-specific rules, patterns, and lessons learned)
   OVERRIDES.md          (user-issued overrides that supersede plan content via /gsd steer)
   QUEUE.md              (append-only log of queued milestones via /gsd queue)
   STATE.md
@@ -100,6 +101,7 @@ All auto-mode work happens inside a worktree at `.gsd/worktrees/<MID>/`. This is
 - **PROJECT.md** is a living document describing what the project is right now - current state only, updated at slice completion when stale
 - **REQUIREMENTS.md** tracks the requirement contract — requirements move between Active, Validated, Deferred, Blocked, and Out of Scope as slices prove or invalidate them. Update at slice completion when evidence supports a status change.
 - **DECISIONS.md** is an append-only register of architectural and pattern decisions - read it during planning/research, append to it during execution when a meaningful decision is made
+- **KNOWLEDGE.md** is an append-only register of project-specific rules, patterns, and lessons learned. Read it at the start of every unit. Append to it when you discover a recurring issue, a non-obvious pattern, or a rule that future agents should follow.
 - **CONTEXT.md** files (milestone or slice level) capture the brief — scope, goals, constraints, and key decisions from discussion. When present, they are the authoritative source for what a milestone or slice is trying to achieve. Read them before planning or executing.
 - **Milestones** are major project phases (M001, M002, ...)
 - **Slices** are demoable vertical increments (S01, S02, ...) ordered by risk. After each slice completes, the roadmap is reassessed before the next slice begins.

package/src/resources/extensions/gsd/queue-order.ts

@@ -0,0 +1,231 @@
+/**
+ * GSD Queue Order — Custom milestone execution ordering.
+ *
+ * Stores an explicit execution order in `.gsd/QUEUE-ORDER.json`.
+ * When present, `findMilestoneIds()` uses this order instead of
+ * the default numeric sort (milestoneIdSort).
+ *
+ * The file is committed to git (not gitignored) so ordering
+ * survives branch switches and is shared across sessions.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { gsdRoot } from "./paths.js";
+import { milestoneIdSort } from "./guided-flow.js";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+interface QueueOrderFile {
+  order: string[];
+  updatedAt: string;
+}
+
+export interface DependencyViolation {
+  milestone: string;
+  dependsOn: string;
+  type: 'would_block' | 'circular' | 'missing_dep';
+  message: string;
+}
+
+export interface DependencyRedundancy {
+  milestone: string;
+  dependsOn: string;
+}
+
+export interface DependencyValidation {
+  valid: boolean;
+  violations: DependencyViolation[];
+  redundant: DependencyRedundancy[];
+}
+
+// ─── Path ────────────────────────────────────────────────────────────────────
+
+function queueOrderPath(basePath: string): string {
+  return join(gsdRoot(basePath), "QUEUE-ORDER.json");
+}
+
+// ─── Read / Write ────────────────────────────────────────────────────────────
+
+/**
+ * Load the custom queue order. Returns null if no file exists or if
+ * the file is corrupt/unreadable.
+ */
+export function loadQueueOrder(basePath: string): string[] | null {
+  const p = queueOrderPath(basePath);
+  if (!existsSync(p)) return null;
+  try {
+    const data: QueueOrderFile = JSON.parse(readFileSync(p, "utf-8"));
+    if (!Array.isArray(data.order)) return null;
+    return data.order;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save a custom queue order to disk.
+ */
+export function saveQueueOrder(basePath: string, order: string[]): void {
+  const data: QueueOrderFile = {
+    order,
+    updatedAt: new Date().toISOString(),
+  };
+  writeFileSync(queueOrderPath(basePath), JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+
+// ─── Sorting ─────────────────────────────────────────────────────────────────
+
+/**
+ * Sort milestone IDs respecting a custom order.
+ *
+ * - IDs present in `customOrder` appear in that exact sequence.
+ * - IDs on disk but NOT in `customOrder` are appended at the end,
+ *   sorted by the default `milestoneIdSort` (numeric).
+ * - IDs in `customOrder` but NOT on disk are silently skipped.
+ * - When `customOrder` is null, falls back to `milestoneIdSort`.
+ */
+export function sortByQueueOrder(ids: string[], customOrder: string[] | null): string[] {
+  if (!customOrder) return [...ids].sort(milestoneIdSort);
+
+  const idSet = new Set(ids);
+  const ordered: string[] = [];
+
+  // First: IDs from customOrder that exist on disk
+  for (const id of customOrder) {
+    if (idSet.has(id)) {
+      ordered.push(id);
+      idSet.delete(id);
+    }
+  }
+
+  // Then: remaining IDs not in customOrder, in default sort order
+  const remaining = [...idSet].sort(milestoneIdSort);
+  return [...ordered, ...remaining];
+}
+
+// ─── Pruning ─────────────────────────────────────────────────────────────────
+
+/**
+ * Remove IDs from the queue order file that are no longer valid
+ * (completed or deleted milestones). No-op if file doesn't exist.
+ */
+export function pruneQueueOrder(basePath: string, validIds: string[]): void {
+  const order = loadQueueOrder(basePath);
+  if (!order) return;
+
+  const validSet = new Set(validIds);
+  const pruned = order.filter(id => validSet.has(id));
+
+  if (pruned.length !== order.length) {
+    saveQueueOrder(basePath, pruned);
+  }
+}
+
+// ─── Validation ──────────────────────────────────────────────────────────────
+
+/**
+ * Validate a proposed queue order against dependency constraints.
+ *
+ * Checks:
+ * - would_block: A milestone is placed before one of its dependencies
+ * - circular: Two or more milestones form a dependency cycle
+ * - missing_dep: A milestone depends on an ID that doesn't exist
+ * - redundant: A dependency is satisfied by queue position (dep comes earlier)
+ */
+export function validateQueueOrder(
+  order: string[],
+  depsMap: Map<string, string[]>,
+  completedIds: Set<string>,
+): DependencyValidation {
+  const violations: DependencyViolation[] = [];
+  const redundant: DependencyRedundancy[] = [];
+
+  const positionMap = new Map<string, number>();
+  for (let i = 0; i < order.length; i++) {
+    positionMap.set(order[i], i);
+  }
+
+  const allKnownIds = new Set([...order, ...completedIds]);
+
+  for (const [mid, deps] of depsMap) {
+    const midPos = positionMap.get(mid);
+    if (midPos === undefined) continue; // not in pending order
+
+    for (const dep of deps) {
+      // Dep already completed — always satisfied
+      if (completedIds.has(dep)) continue;
+
+      // Dep doesn't exist anywhere
+      if (!allKnownIds.has(dep)) {
+        violations.push({
+          milestone: mid,
+          dependsOn: dep,
+          type: 'missing_dep',
+          message: `${mid} depends on ${dep}, but ${dep} does not exist.`,
+        });
+        continue;
+      }
+
+      const depPos = positionMap.get(dep);
+      if (depPos === undefined) continue; // dep not in pending order (edge case)
+
+      if (depPos > midPos) {
+        // Dep comes AFTER this milestone in the order — violation
+        violations.push({
+          milestone: mid,
+          dependsOn: dep,
+          type: 'would_block',
+          message: `${mid} cannot run before ${dep} — ${mid} depends_on: [${dep}].`,
+        });
+      } else {
+        // Dep comes before — satisfied by position, redundant
+        redundant.push({ milestone: mid, dependsOn: dep });
+      }
+    }
+  }
+
+  // Check for circular dependencies
+  const visited = new Set<string>();
+  const inStack = new Set<string>();
+
+  function hasCycle(node: string, path: string[]): string[] | null {
+    if (inStack.has(node)) return [...path, node];
+    if (visited.has(node)) return null;
+
+    visited.add(node);
+    inStack.add(node);
+
+    const deps = depsMap.get(node) ?? [];
+    for (const dep of deps) {
+      if (completedIds.has(dep)) continue;
+      const cycle = hasCycle(dep, [...path, node]);
+      if (cycle) return cycle;
+    }
+
+    inStack.delete(node);
+    return null;
+  }
+
+  for (const mid of order) {
+    if (!visited.has(mid)) {
+      const cycle = hasCycle(mid, []);
+      if (cycle) {
+        const cycleStr = cycle.join(' → ');
+        violations.push({
+          milestone: cycle[0],
+          dependsOn: cycle[cycle.length - 2],
+          type: 'circular',
+          message: `Circular dependency: ${cycleStr}`,
+        });
+        break; // one cycle report is enough
+      }
+    }
+  }
+
+  return {
+    valid: violations.length === 0,
+    violations,
+    redundant,
+  };
+}