gsd-pi 2.33.1 → 2.34.0-dev.bbb5216

package/dist/resources/extensions/gsd/preferences.js

@@ -0,0 +1,325 @@
+/**
+ * GSD Preferences -- loading, merging, and rendering.
+ *
+ * This module is the primary entry point for preference operations.
+ * Type definitions live in ./preferences-types.js, validation in
+ * ./preferences-validation.js, skill logic in ./preferences-skills.js,
+ * and model logic in ./preferences-models.js.
+ *
+ * All symbols are re-exported here so that existing `import { ... } from "./preferences.js"`
+ * statements continue to work without modification.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { gsdRoot } from "./paths.js";
+import { parse as parseYaml } from "yaml";
+import { normalizeStringArray } from "../shared/mod.js";
+import { MODE_DEFAULTS, } from "./preferences-types.js";
+import { validatePreferences } from "./preferences-validation.js";
+import { formatSkillRef } from "./preferences-skills.js";
+// ─── Re-exports: validation ─────────────────────────────────────────────────
+export { validatePreferences } from "./preferences-validation.js";
+// ─── Re-exports: skills ─────────────────────────────────────────────────────
+export { resolveAllSkillReferences, resolveSkillDiscoveryMode, resolveSkillStalenessDays, } from "./preferences-skills.js";
+// ─── Re-exports: models ─────────────────────────────────────────────────────
+export { resolveModelForUnit, resolveModelWithFallbacksForUnit, getNextFallbackModel, isTransientNetworkError, validateModelId, updatePreferencesModels, resolveDynamicRoutingConfig, resolveAutoSupervisorConfig, resolveProfileDefaults, resolveEffectiveProfile, resolveInlineLevel, resolveCompressionStrategy, resolveContextSelection, resolveSearchProviderFromPreferences, } from "./preferences-models.js";
+// ─── Path Constants & Getters ───────────────────────────────────────────────
+const GLOBAL_PREFERENCES_PATH = join(homedir(), ".gsd", "preferences.md");
+const LEGACY_GLOBAL_PREFERENCES_PATH = join(homedir(), ".pi", "agent", "gsd-preferences.md");
+function projectPreferencesPath() {
+    return join(gsdRoot(process.cwd()), "preferences.md");
+}
+// Bootstrap in gitignore.ts historically created PREFERENCES.md (uppercase) by mistake.
+// Check uppercase as a fallback so those files aren't silently ignored.
+const GLOBAL_PREFERENCES_PATH_UPPERCASE = join(homedir(), ".gsd", "PREFERENCES.md");
+function projectPreferencesPathUppercase() {
+    return join(gsdRoot(process.cwd()), "PREFERENCES.md");
+}
+export function getGlobalGSDPreferencesPath() {
+    return GLOBAL_PREFERENCES_PATH;
+}
+export function getLegacyGlobalGSDPreferencesPath() {
+    return LEGACY_GLOBAL_PREFERENCES_PATH;
+}
+export function getProjectGSDPreferencesPath() {
+    return projectPreferencesPath();
+}
+// ─── Loading ────────────────────────────────────────────────────────────────
+export function loadGlobalGSDPreferences() {
+    return loadPreferencesFile(GLOBAL_PREFERENCES_PATH, "global")
+        ?? loadPreferencesFile(GLOBAL_PREFERENCES_PATH_UPPERCASE, "global")
+        ?? loadPreferencesFile(LEGACY_GLOBAL_PREFERENCES_PATH, "global");
+}
+export function loadProjectGSDPreferences() {
+    return loadPreferencesFile(projectPreferencesPath(), "project")
+        ?? loadPreferencesFile(projectPreferencesPathUppercase(), "project");
+}
+export function loadEffectiveGSDPreferences() {
+    const globalPreferences = loadGlobalGSDPreferences();
+    const projectPreferences = loadProjectGSDPreferences();
+    if (!globalPreferences && !projectPreferences)
+        return null;
+    let result;
+    if (!globalPreferences) {
+        result = projectPreferences;
+    }
+    else if (!projectPreferences) {
+        result = globalPreferences;
+    }
+    else {
+        const mergedWarnings = [
+            ...(globalPreferences.warnings ?? []),
+            ...(projectPreferences.warnings ?? []),
+        ];
+        result = {
+            path: projectPreferences.path,
+            scope: "project",
+            preferences: mergePreferences(globalPreferences.preferences, projectPreferences.preferences),
+            ...(mergedWarnings.length > 0 ? { warnings: mergedWarnings } : {}),
+        };
+    }
+    // Apply mode defaults as the lowest-priority layer
+    if (result.preferences.mode) {
+        result = {
+            ...result,
+            preferences: applyModeDefaults(result.preferences.mode, result.preferences),
+        };
+    }
+    return result;
+}
+function loadPreferencesFile(path, scope) {
+    if (!existsSync(path))
+        return null;
+    const raw = readFileSync(path, "utf-8");
+    const preferences = parsePreferencesMarkdown(raw);
+    if (!preferences)
+        return null;
+    const validation = validatePreferences(preferences);
+    const allWarnings = [...validation.warnings, ...validation.errors];
+    return {
+        path,
+        scope,
+        preferences: validation.preferences,
+        ...(allWarnings.length > 0 ? { warnings: allWarnings } : {}),
+    };
+}
+/** @internal Exported for testing only */
+export function parsePreferencesMarkdown(content) {
+    // Use indexOf instead of [\s\S]*? regex to avoid backtracking (#468)
+    const startMarker = content.startsWith('---\r\n') ? '---\r\n' : '---\n';
+    if (!content.startsWith(startMarker))
+        return null;
+    const searchStart = startMarker.length;
+    const endIdx = content.indexOf('\n---', searchStart);
+    if (endIdx === -1)
+        return null;
+    const block = content.slice(searchStart, endIdx);
+    return parseFrontmatterBlock(block.replace(/\r/g, ''));
+}
+function parseFrontmatterBlock(frontmatter) {
+    try {
+        const parsed = parseYaml(frontmatter);
+        if (typeof parsed !== 'object' || parsed === null) {
+            return {};
+        }
+        return parsed;
+    }
+    catch (e) {
+        console.error("[parseFrontmatterBlock] YAML parse error:", e);
+        return {};
+    }
+}
+// ─── Merging ────────────────────────────────────────────────────────────────
+/**
+ * Apply mode defaults as the lowest-priority layer.
+ * Mode defaults fill in undefined fields; any explicit user value wins.
+ */
+export function applyModeDefaults(mode, prefs) {
+    const defaults = MODE_DEFAULTS[mode];
+    if (!defaults)
+        return prefs;
+    return mergePreferences(defaults, prefs);
+}
+function mergePreferences(base, override) {
+    return {
+        version: override.version ?? base.version,
+        mode: override.mode ?? base.mode,
+        always_use_skills: mergeStringLists(base.always_use_skills, override.always_use_skills),
+        prefer_skills: mergeStringLists(base.prefer_skills, override.prefer_skills),
+        avoid_skills: mergeStringLists(base.avoid_skills, override.avoid_skills),
+        skill_rules: [...(base.skill_rules ?? []), ...(override.skill_rules ?? [])],
+        custom_instructions: mergeStringLists(base.custom_instructions, override.custom_instructions),
+        models: { ...(base.models ?? {}), ...(override.models ?? {}) },
+        skill_discovery: override.skill_discovery ?? base.skill_discovery,
+        skill_staleness_days: override.skill_staleness_days ?? base.skill_staleness_days,
+        auto_supervisor: { ...(base.auto_supervisor ?? {}), ...(override.auto_supervisor ?? {}) },
+        uat_dispatch: override.uat_dispatch ?? base.uat_dispatch,
+        unique_milestone_ids: override.unique_milestone_ids ?? base.unique_milestone_ids,
+        budget_ceiling: override.budget_ceiling ?? base.budget_ceiling,
+        budget_enforcement: override.budget_enforcement ?? base.budget_enforcement,
+        context_pause_threshold: override.context_pause_threshold ?? base.context_pause_threshold,
+        notifications: (base.notifications || override.notifications)
+            ? { ...(base.notifications ?? {}), ...(override.notifications ?? {}) }
+            : undefined,
+        remote_questions: override.remote_questions
+            ? { ...(base.remote_questions ?? {}), ...override.remote_questions }
+            : base.remote_questions,
+        git: (base.git || override.git)
+            ? { ...(base.git ?? {}), ...(override.git ?? {}) }
+            : 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),
+        dynamic_routing: (base.dynamic_routing || override.dynamic_routing)
+            ? { ...(base.dynamic_routing ?? {}), ...(override.dynamic_routing ?? {}) }
+            : undefined,
+        token_profile: override.token_profile ?? base.token_profile,
+        phases: (base.phases || override.phases)
+            ? { ...(base.phases ?? {}), ...(override.phases ?? {}) }
+            : undefined,
+        parallel: (base.parallel || override.parallel)
+            ? { ...(base.parallel ?? {}), ...(override.parallel ?? {}) }
+            : undefined,
+        verification_commands: mergeStringLists(base.verification_commands, override.verification_commands),
+        verification_auto_fix: override.verification_auto_fix ?? base.verification_auto_fix,
+        verification_max_retries: override.verification_max_retries ?? base.verification_max_retries,
+        search_provider: override.search_provider ?? base.search_provider,
+        compression_strategy: override.compression_strategy ?? base.compression_strategy,
+        context_selection: override.context_selection ?? base.context_selection,
+    };
+}
+function mergeStringLists(base, override) {
+    const merged = [
+        ...normalizeStringArray(base),
+        ...normalizeStringArray(override),
+    ]
+        .map((item) => item.trim())
+        .filter(Boolean);
+    return merged.length > 0 ? Array.from(new Set(merged)) : undefined;
+}
+function mergePostUnitHooks(base, override) {
+    if (!base?.length && !override?.length)
+        return undefined;
+    const merged = [...(base ?? [])];
+    for (const hook of override ?? []) {
+        // Override hooks with same name replace base hooks
+        const idx = merged.findIndex(h => h.name === hook.name);
+        if (idx >= 0) {
+            merged[idx] = hook;
+        }
+        else {
+            merged.push(hook);
+        }
+    }
+    return merged.length > 0 ? merged : undefined;
+}
+function mergePreDispatchHooks(base, override) {
+    if (!base?.length && !override?.length)
+        return undefined;
+    const merged = [...(base ?? [])];
+    for (const hook of override ?? []) {
+        const idx = merged.findIndex(h => h.name === hook.name);
+        if (idx >= 0) {
+            merged[idx] = hook;
+        }
+        else {
+            merged.push(hook);
+        }
+    }
+    return merged.length > 0 ? merged : undefined;
+}
+// ─── System Prompt Rendering ──────────────────────────────────────────────────
+export function renderPreferencesForSystemPrompt(preferences, resolutions) {
+    const validated = validatePreferences(preferences);
+    const lines = ["## GSD Skill Preferences"];
+    if (validated.errors.length > 0) {
+        lines.push("- Validation: some preference values were ignored because they were invalid.");
+    }
+    for (const warning of validated.warnings) {
+        lines.push(`- Deprecation: ${warning}`);
+    }
+    preferences = validated.preferences;
+    lines.push("- Treat these as explicit skill-selection policy for GSD work.", "- If a listed skill exists and is relevant, load and follow it instead of treating it as a vague suggestion.", "- Current user instructions still override these defaults.");
+    const fmt = (ref) => resolutions ? formatSkillRef(ref, resolutions) : ref;
+    if (preferences.always_use_skills && preferences.always_use_skills.length > 0) {
+        lines.push("- Always use these skills when relevant:");
+        for (const skill of preferences.always_use_skills) {
+            lines.push(`  - ${fmt(skill)}`);
+        }
+    }
+    if (preferences.prefer_skills && preferences.prefer_skills.length > 0) {
+        lines.push("- Prefer these skills when relevant:");
+        for (const skill of preferences.prefer_skills) {
+            lines.push(`  - ${fmt(skill)}`);
+        }
+    }
+    if (preferences.avoid_skills && preferences.avoid_skills.length > 0) {
+        lines.push("- Avoid these skills unless clearly needed:");
+        for (const skill of preferences.avoid_skills) {
+            lines.push(`  - ${fmt(skill)}`);
+        }
+    }
+    if (preferences.skill_rules && preferences.skill_rules.length > 0) {
+        lines.push("- Situational rules:");
+        for (const rule of preferences.skill_rules) {
+            lines.push(`  - When ${rule.when}:`);
+            if (rule.use && rule.use.length > 0) {
+                lines.push(`    - use: ${rule.use.map(fmt).join(", ")}`);
+            }
+            if (rule.prefer && rule.prefer.length > 0) {
+                lines.push(`    - prefer: ${rule.prefer.map(fmt).join(", ")}`);
+            }
+            if (rule.avoid && rule.avoid.length > 0) {
+                lines.push(`    - avoid: ${rule.avoid.map(fmt).join(", ")}`);
+            }
+        }
+    }
+    if (preferences.custom_instructions && preferences.custom_instructions.length > 0) {
+        lines.push("- Additional instructions:");
+        for (const instruction of preferences.custom_instructions) {
+            lines.push(`  - ${instruction}`);
+        }
+    }
+    return lines.join("\n");
+}
+// ─── Hook Resolution ──────────────────────────────────────────────────────────
+/**
+ * Resolve enabled post-unit hooks from effective preferences.
+ * Returns an empty array when no hooks are configured.
+ */
+export function resolvePostUnitHooks() {
+    const prefs = loadEffectiveGSDPreferences();
+    return (prefs?.preferences.post_unit_hooks ?? [])
+        .filter(h => h.enabled !== false);
+}
+/**
+ * Resolve enabled pre-dispatch hooks from effective preferences.
+ * Returns an empty array when no hooks are configured.
+ */
+export function resolvePreDispatchHooks() {
+    const prefs = loadEffectiveGSDPreferences();
+    return (prefs?.preferences.pre_dispatch_hooks ?? [])
+        .filter(h => h.enabled !== false);
+}
+// ─── Isolation & Parallel ─────────────────────────────────────────────────────
+/**
+ * Resolve the effective git isolation mode from preferences.
+ * Returns "worktree" (default), "branch", or "none".
+ */
+export function getIsolationMode() {
+    const prefs = loadEffectiveGSDPreferences()?.preferences?.git;
+    if (prefs?.isolation === "none")
+        return "none";
+    if (prefs?.isolation === "branch")
+        return "branch";
+    return "worktree"; // default
+}
+export function resolveParallelConfig(prefs) {
+    return {
+        enabled: prefs?.parallel?.enabled ?? false,
+        max_workers: Math.max(1, Math.min(4, prefs?.parallel?.max_workers ?? 2)),
+        budget_ceiling: prefs?.parallel?.budget_ceiling,
+        merge_strategy: prefs?.parallel?.merge_strategy ?? "per-milestone",
+        auto_merge: prefs?.parallel?.auto_merge ?? "confirm",
+    };
+}

package/dist/resources/extensions/gsd/progress-score.js

@@ -0,0 +1,102 @@
+/**
+ * GSD Progress Score — Traffic Light Status Indicator (#1221)
+ *
+ * Combines existing health signals into a single at-a-glance status:
+ *   - Green: progressing well
+ *   - Yellow: struggling (retries, warnings)
+ *   - Red: stuck (loops, persistent errors, no activity)
+ *
+ * Purely derived — no stored state. Reads from doctor-proactive health
+ * tracking, stuck detection counters, and working-tree activity.
+ */
+import { getHealthTrend, getConsecutiveErrorUnits, getHealthHistory, } from "./doctor-proactive.js";
+function escalateLevel(level, next) {
+    const ranks = {
+        green: 0,
+        yellow: 1,
+        red: 2,
+    };
+    return ranks[next] > ranks[level] ? next : level;
+}
+// ── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Compute the current progress score from health signals.
+ */
+export function computeProgressScore() {
+    const signals = [];
+    let level = "green";
+    // Check consecutive errors
+    const consecutiveErrors = getConsecutiveErrorUnits();
+    if (consecutiveErrors >= 3) {
+        signals.push({ kind: "negative", label: `${consecutiveErrors} consecutive error units` });
+        level = escalateLevel(level, "red");
+    }
+    else if (consecutiveErrors >= 1) {
+        signals.push({ kind: "negative", label: `${consecutiveErrors} consecutive error unit(s)` });
+        level = escalateLevel(level, "yellow");
+    }
+    // Check health trend
+    const trend = getHealthTrend();
+    if (trend === "degrading") {
+        signals.push({ kind: "negative", label: "Health trend declining" });
+        level = escalateLevel(level, "yellow");
+    }
+    else if (trend === "improving") {
+        signals.push({ kind: "positive", label: "Health trend improving" });
+    }
+    else if (trend === "stable") {
+        signals.push({ kind: "neutral", label: "Health trend stable" });
+    }
+    // Check recent history
+    const history = getHealthHistory();
+    if (history.length === 0) {
+        signals.push({ kind: "neutral", label: "No health data yet" });
+    }
+    const summary = level === "green"
+        ? "Progressing well"
+        : level === "yellow"
+            ? "Some issues detected"
+            : "Stuck or erroring";
+    return { level, summary, signals };
+}
+/**
+ * Compute progress score with additional context for dashboard display.
+ */
+export function computeProgressScoreWithContext(context) {
+    const base = computeProgressScore();
+    if (context.sameUnitCount && context.sameUnitCount >= 3) {
+        base.signals.push({ kind: "negative", label: `Same unit dispatched ${context.sameUnitCount}× consecutively` });
+        base.level = escalateLevel(base.level, "red");
+        base.summary = "Stuck on same unit";
+    }
+    else if (context.sameUnitCount && context.sameUnitCount >= 2) {
+        base.signals.push({ kind: "negative", label: `Same unit dispatched ${context.sameUnitCount}×` });
+        base.level = escalateLevel(base.level, "yellow");
+    }
+    if (context.recoveryCount && context.recoveryCount > 0) {
+        base.signals.push({ kind: "negative", label: `${context.recoveryCount} recovery attempts` });
+        base.level = escalateLevel(base.level, "yellow");
+    }
+    if (context.completedCount && context.completedCount > 0) {
+        base.signals.push({ kind: "positive", label: `${context.completedCount} units completed` });
+    }
+    return base;
+}
+/**
+ * Format a one-line progress indicator for dashboard/status display.
+ */
+export function formatProgressLine(score) {
+    const icon = score.level === "green" ? "●" : score.level === "yellow" ? "◐" : "○";
+    return `${icon} ${score.summary}`;
+}
+/**
+ * Format a multi-line progress report.
+ */
+export function formatProgressReport(score) {
+    const lines = [formatProgressLine(score)];
+    for (const signal of score.signals) {
+        const prefix = signal.kind === "positive" ? "  ✓" : signal.kind === "negative" ? "  ✗" : "  ·";
+        lines.push(`${prefix} ${signal.label}`);
+    }
+    return lines.join("\n");
+}

package/dist/resources/extensions/gsd/prompt-cache-optimizer.js

@@ -0,0 +1,150 @@
+/**
+ * Prompt Cache Optimizer — separates prompt content into cacheable static
+ * prefixes and dynamic per-task suffixes to maximize provider cache hit rates.
+ *
+ * Anthropic caches by prefix match (up to 4 breakpoints, 90% savings).
+ * OpenAI auto-caches prompts with 1024+ stable prefix tokens (50% savings).
+ * Both benefit from placing static content first and dynamic content last.
+ */
+// ─── Label classification maps ───────────────────────────────────────────────
+/** Labels that never change within a session */
+const STATIC_LABELS = new Set([
+    "system-prompt",
+    "base-instructions",
+    "executor-constraints",
+]);
+/** Prefix patterns for static labels (e.g. "template-*") */
+const STATIC_PREFIXES = ["template-"];
+/** Labels that change per-slice but not per-task */
+const SEMI_STATIC_LABELS = new Set([
+    "slice-plan",
+    "decisions",
+    "requirements",
+    "roadmap",
+    "prior-summaries",
+    "project-context",
+    "overrides",
+]);
+/** Labels that change per-task */
+const DYNAMIC_LABELS = new Set([
+    "task-plan",
+    "task-instructions",
+    "task-context",
+    "file-contents",
+    "diff-context",
+    "verification-commands",
+]);
+// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Classify common GSD prompt sections by their caching potential.
+ * Returns the appropriate ContentRole for a section label.
+ */
+export function classifySection(label) {
+    if (STATIC_LABELS.has(label))
+        return "static";
+    if (STATIC_PREFIXES.some((p) => label.startsWith(p)))
+        return "static";
+    if (SEMI_STATIC_LABELS.has(label))
+        return "semi-static";
+    if (DYNAMIC_LABELS.has(label))
+        return "dynamic";
+    // Conservative default: unknown labels are treated as dynamic
+    return "dynamic";
+}
+/**
+ * Build a PromptSection from content with automatic role classification.
+ *
+ * @param label Section label (e.g., "slice-plan", "task-instructions")
+ * @param content The section content
+ * @param role Optional explicit role override
+ */
+export function section(label, content, role) {
+    return {
+        label,
+        content,
+        role: role ?? classifySection(label),
+    };
+}
+/**
+ * Optimize prompt sections for maximum cache hit rates.
+ * Reorders sections: static first, then semi-static, then dynamic.
+ * Preserves relative order within each role group.
+ *
+ * @param sections Array of labeled prompt sections
+ * @returns Cache-optimized prompt with statistics
+ */
+export function optimizeForCaching(sections) {
+    const groups = {
+        static: [],
+        "semi-static": [],
+        dynamic: [],
+    };
+    for (const s of sections) {
+        groups[s.role].push(s);
+    }
+    const ordered = [
+        ...groups["static"],
+        ...groups["semi-static"],
+        ...groups["dynamic"],
+    ];
+    const prompt = ordered.map((s) => s.content).join("\n\n");
+    const staticChars = groups["static"].reduce((sum, s) => sum + s.content.length, 0);
+    const semiStaticChars = groups["semi-static"].reduce((sum, s) => sum + s.content.length, 0);
+    // Account for separator characters between sections in the cacheable prefix
+    const staticSeparators = groups["static"].length > 0
+        ? (groups["static"].length - 1) * 2 // "\n\n" between static sections
+        : 0;
+    const semiStaticSeparators = groups["semi-static"].length > 0
+        ? (groups["semi-static"].length - 1) * 2
+        : 0;
+    // Separator between static and semi-static groups
+    const groupSeparator = groups["static"].length > 0 && groups["semi-static"].length > 0 ? 2 : 0;
+    const cacheablePrefixChars = staticChars +
+        semiStaticChars +
+        staticSeparators +
+        semiStaticSeparators +
+        groupSeparator;
+    const totalChars = prompt.length;
+    const cacheEfficiency = totalChars > 0 ? cacheablePrefixChars / totalChars : 0;
+    return {
+        prompt,
+        cacheablePrefixChars,
+        totalChars,
+        cacheEfficiency,
+        sectionCounts: {
+            static: groups["static"].length,
+            "semi-static": groups["semi-static"].length,
+            dynamic: groups["dynamic"].length,
+        },
+    };
+}
+/**
+ * Estimate the cache savings for a given optimization result.
+ * Based on provider pricing:
+ * - Anthropic: 90% savings on cached tokens
+ * - OpenAI: 50% savings on cached tokens
+ *
+ * @param result The cache-optimized prompt
+ * @param provider Provider name for savings calculation
+ * @returns Estimated savings as a decimal (0.0-1.0)
+ */
+export function estimateCacheSavings(result, provider) {
+    switch (provider) {
+        case "anthropic":
+            return result.cacheEfficiency * 0.9;
+        case "openai":
+            return result.cacheEfficiency * 0.5;
+        case "other":
+            return 0;
+    }
+}
+/**
+ * Compute cache hit rate from token usage metrics.
+ * Returns a percentage 0-100.
+ */
+export function computeCacheHitRate(usage) {
+    const denominator = usage.cacheRead + usage.input;
+    if (denominator === 0)
+        return 0;
+    return (usage.cacheRead / denominator) * 100;
+}