gsd-pi 2.33.1-dev.29a8268 → 2.33.1-dev.9bafd68

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,197 @@
+/**
+ * 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";
+// ── Signal Evaluators ──────────────────────────────────────────────────────
+function evaluateHealthTrend() {
+    const trend = getHealthTrend();
+    switch (trend) {
+        case "improving":
+            return { name: "health_trend", level: "green", detail: "Health improving" };
+        case "stable":
+            return { name: "health_trend", level: "green", detail: "Health stable" };
+        case "degrading":
+            return { name: "health_trend", level: "red", detail: "Health degrading" };
+        case "unknown":
+            return { name: "health_trend", level: "green", detail: "Insufficient data" };
+    }
+}
+function evaluateErrorStreak() {
+    const streak = getConsecutiveErrorUnits();
+    if (streak === 0) {
+        return { name: "error_streak", level: "green", detail: "No consecutive errors" };
+    }
+    if (streak <= 2) {
+        return { name: "error_streak", level: "yellow", detail: `${streak} consecutive error unit(s)` };
+    }
+    return { name: "error_streak", level: "red", detail: `${streak} consecutive error units` };
+}
+function evaluateRecentErrors() {
+    const history = getHealthHistory();
+    if (history.length === 0) {
+        return { name: "recent_errors", level: "green", detail: "No health data yet" };
+    }
+    const latest = history[history.length - 1];
+    if (latest.errors === 0 && latest.warnings <= 1) {
+        return { name: "recent_errors", level: "green", detail: `${latest.errors}E/${latest.warnings}W` };
+    }
+    if (latest.errors === 0) {
+        return { name: "recent_errors", level: "yellow", detail: `${latest.warnings} warning(s)` };
+    }
+    if (latest.errors <= 2) {
+        return { name: "recent_errors", level: "yellow", detail: `${latest.errors} error(s), ${latest.warnings} warning(s)` };
+    }
+    return { name: "recent_errors", level: "red", detail: `${latest.errors} error(s), ${latest.warnings} warning(s)` };
+}
+function evaluateArtifactProduction() {
+    const history = getHealthHistory();
+    if (history.length < 2) {
+        return { name: "artifact_production", level: "green", detail: "Insufficient data" };
+    }
+    const totalFixes = history.reduce((sum, s) => sum + s.fixesApplied, 0);
+    const recent = history.slice(-3);
+    const recentFixes = recent.reduce((sum, s) => sum + s.fixesApplied, 0);
+    // If recent units are all producing fixes but errors aren't decreasing,
+    // doctor is fighting fires but not making headway
+    if (recentFixes > 3 && recent.every(s => s.errors > 0)) {
+        return { name: "artifact_production", level: "yellow", detail: "Doctor applying fixes but errors persist" };
+    }
+    return { name: "artifact_production", level: "green", detail: `${totalFixes} total fixes applied` };
+}
+function evaluateDispatchVelocity() {
+    const history = getHealthHistory();
+    if (history.length < 3) {
+        return { name: "dispatch_velocity", level: "green", detail: "Insufficient data" };
+    }
+    // Check time between recent snapshots — are units completing at a reasonable rate?
+    const recent = history.slice(-5);
+    if (recent.length < 2) {
+        return { name: "dispatch_velocity", level: "green", detail: "Insufficient data" };
+    }
+    const timeDiffs = [];
+    for (let i = 1; i < recent.length; i++) {
+        timeDiffs.push(recent[i].timestamp - recent[i - 1].timestamp);
+    }
+    const avgTimeMs = timeDiffs.reduce((a, b) => a + b, 0) / timeDiffs.length;
+    const avgTimeMins = Math.round(avgTimeMs / 60_000);
+    // If average unit time is > 15 minutes, something might be wrong
+    if (avgTimeMins > 15) {
+        return { name: "dispatch_velocity", level: "yellow", detail: `Units averaging ${avgTimeMins}min each` };
+    }
+    return { name: "dispatch_velocity", level: "green", detail: `Units averaging ${avgTimeMins || "<1"}min each` };
+}
+// ── Main API ───────────────────────────────────────────────────────────────
+/**
+ * Compute the current progress score by evaluating all available signals.
+ * Returns a composite score with individual signal details.
+ */
+export function computeProgressScore() {
+    const signals = [
+        evaluateHealthTrend(),
+        evaluateErrorStreak(),
+        evaluateRecentErrors(),
+        evaluateArtifactProduction(),
+        evaluateDispatchVelocity(),
+    ];
+    // Overall level: worst of all signals
+    const level = signals.some(s => s.level === "red")
+        ? "red"
+        : signals.some(s => s.level === "yellow")
+            ? "yellow"
+            : "green";
+    // Build summary from the most important signals
+    const summary = buildSummary(level, signals);
+    return { level, summary, signals };
+}
+/**
+ * Compute progress score with additional context from the current unit.
+ */
+export function computeProgressScoreWithContext(context) {
+    const base = computeProgressScore();
+    // Add retry signal if available
+    if (context.retryCount !== undefined && context.maxRetries !== undefined) {
+        const retrySignal = context.retryCount === 0
+            ? { name: "retry_count", level: "green", detail: "No retries" }
+            : context.retryCount <= 2
+                ? { name: "retry_count", level: "yellow", detail: `Retry ${context.retryCount}/${context.maxRetries}` }
+                : { name: "retry_count", level: "red", detail: `Retry ${context.retryCount}/${context.maxRetries} — looping` };
+        base.signals.push(retrySignal);
+        // Re-evaluate level
+        if (retrySignal.level === "red")
+            base.level = "red";
+        else if (retrySignal.level === "yellow" && base.level === "green")
+            base.level = "yellow";
+    }
+    // Build richer summary with context
+    base.summary = buildSummaryWithContext(base.level, base.signals, context);
+    return base;
+}
+// ── Formatting ─────────────────────────────────────────────────────────────
+function buildSummary(level, signals) {
+    switch (level) {
+        case "green":
+            return "Progressing well";
+        case "yellow": {
+            const issues = signals.filter(s => s.level === "yellow").map(s => s.detail);
+            return `Struggling — ${issues[0] ?? "minor issues detected"}`;
+        }
+        case "red": {
+            const issues = signals.filter(s => s.level === "red").map(s => s.detail);
+            return `Stuck — ${issues[0] ?? "critical issues detected"}`;
+        }
+    }
+}
+function buildSummaryWithContext(level, signals, context) {
+    const unitLabel = context.currentUnitId
+        ? ` ${context.currentUnitId}`
+        : "";
+    const progressLabel = context.completedUnits !== undefined && context.totalUnits !== undefined
+        ? ` (${context.completedUnits} of ${context.totalUnits} done)`
+        : "";
+    switch (level) {
+        case "green":
+            return `Progressing well —${unitLabel}${progressLabel}`;
+        case "yellow": {
+            const issues = signals.filter(s => s.level === "yellow").map(s => s.detail);
+            const retryInfo = context.retryCount ? `, attempt ${context.retryCount}/${context.maxRetries}` : "";
+            return `Struggling —${unitLabel}${retryInfo}${progressLabel ? ` ${progressLabel}` : ""}, ${issues[0] ?? "issues detected"}`;
+        }
+        case "red": {
+            const issues = signals.filter(s => s.level === "red").map(s => s.detail);
+            return `Stuck —${unitLabel}${progressLabel ? ` ${progressLabel}` : ""}, ${issues[0] ?? "critical issues"}`;
+        }
+    }
+}
+/**
+ * Format progress score as a single-line traffic light for TUI display.
+ */
+export function formatProgressLine(score) {
+    const icon = score.level === "green" ? "\uD83D\uDFE2"
+        : score.level === "yellow" ? "\uD83D\uDFE1"
+            : "\uD83D\uDD34";
+    return `${icon} ${score.summary}`;
+}
+/**
+ * Format a detailed progress report showing all signals.
+ */
+export function formatProgressReport(score) {
+    const lines = [];
+    lines.push(formatProgressLine(score));
+    lines.push("");
+    lines.push("Signals:");
+    for (const signal of score.signals) {
+        const icon = signal.level === "green" ? "\u2705"
+            : signal.level === "yellow" ? "\u26A0\uFE0F"
+                : "\uD83D\uDED1";
+        lines.push(`  ${icon} ${signal.name}: ${signal.detail}`);
+    }
+    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;
+}