gsd-pi 2.16.0 → 2.17.0

package/dist/resources/extensions/gsd/complexity.ts

@@ -0,0 +1,236 @@
+/**
+ * GSD Task Complexity Classification
+ *
+ * Classifies task plans and unit types by complexity to enable model routing.
+ * Pure heuristics + adaptive learning — no LLM calls, sub-millisecond.
+ *
+ * Combined approach:
+ * - Task plan analysis (step count, file count, description length, signal words)
+ * - Unit type defaults (complete-slice → light, replan → heavy, etc.)
+ * - Budget pressure thresholds (50/75/90% graduated downgrade)
+ * - Adaptive learning via routing-history (optional)
+ *
+ * Classification output uses our TokenProfile-aligned TaskComplexity type
+ * for the simple classifier, and ComplexityTier for the full unit classifier.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ComplexityTier, ClassificationResult, TaskMetadata } from "./types.js";
+
+// Re-export for convenience
+export type { ComplexityTier, ClassificationResult, TaskMetadata };
+
+// ─── Simple Task Complexity (for task plan analysis) ──────────────────────
+
+export type TaskComplexity = "simple" | "standard" | "complex";
+
+/** Words that signal non-trivial work requiring full reasoning capacity */
+const COMPLEXITY_SIGNALS = [
+  "research", "investigate", "refactor", "migrate", "integrate",
+  "complex", "architect", "redesign", "security", "performance",
+  "concurrent", "parallel", "distributed", "backward.?compat",
+  "migration", "architecture", "concurrency", "compatibility",
+];
+const COMPLEXITY_PATTERN = new RegExp(COMPLEXITY_SIGNALS.join("|"), "i");
+
+/**
+ * Classify a task plan by its structural complexity.
+ * Used by dispatch to select execution_simple vs execution model.
+ */
+export function classifyTaskComplexity(planContent: string): TaskComplexity {
+  if (!planContent || planContent.trim().length === 0) return "standard";
+
+  const stepsMatch = planContent.match(/##\s*Steps\s*\n([\s\S]*?)(?=\n##|\n---|$)/i);
+  const stepsSection = stepsMatch?.[1] ?? "";
+  const stepCount = (stepsSection.match(/^\s*\d+\.\s/gm) ?? []).length;
+
+  if (!stepsMatch) return "standard";
+
+  const stepsIdx = planContent.search(/##\s*Steps/i);
+  const descriptionLength = stepsIdx > 0 ? planContent.slice(0, stepsIdx).length : planContent.length;
+
+  const filePatterns = planContent.match(/`[a-zA-Z0-9_/.-]+\.[a-z]{1,4}`/g) ?? [];
+  const uniqueFiles = new Set(filePatterns.map(f => f.replace(/`/g, "")));
+  const fileCount = uniqueFiles.size;
+
+  const hasComplexitySignals = COMPLEXITY_PATTERN.test(planContent);
+
+  // Count fenced code blocks (from #579 Phase 4)
+  const codeBlockCount = (planContent.match(/^```/gm) ?? []).length / 2;
+
+  if (stepCount >= 8 || fileCount >= 8 || descriptionLength > 2000 || codeBlockCount >= 5) {
+    return "complex";
+  }
+
+  if (stepCount <= 3 && descriptionLength < 500 && fileCount <= 3 && !hasComplexitySignals) {
+    return "simple";
+  }
+
+  return "standard";
+}
+
+// ─── Unit Type → Default Tier Mapping (from #579) ─────────────────────────
+
+const UNIT_TYPE_TIERS: Record<string, ComplexityTier> = {
+  // Light: structured summaries, completion, UAT
+  "complete-slice": "light",
+  "run-uat": "light",
+
+  // Standard: research, routine planning
+  "research-milestone": "standard",
+  "research-slice": "standard",
+  "plan-milestone": "standard",
+  "plan-slice": "standard",
+
+  // Heavy: execution default (upgraded by metadata), replanning
+  "execute-task": "standard",
+  "replan-slice": "heavy",
+  "reassess-roadmap": "heavy",
+  "complete-milestone": "standard",
+};
+
+/**
+ * Classify unit complexity for model routing.
+ * Uses unit type defaults, task metadata analysis, and budget pressure.
+ *
+ * @param unitType  The type of unit being dispatched
+ * @param unitId    The unit ID (e.g. "M001/S01/T01")
+ * @param basePath  Project base path (for reading task plans)
+ * @param budgetPct Current budget usage as fraction (0.0-1.0+), or undefined
+ * @param metadata  Optional pre-parsed task metadata
+ */
+export function classifyUnitComplexity(
+  unitType: string,
+  unitId: string,
+  basePath: string,
+  budgetPct?: number,
+  metadata?: TaskMetadata,
+): ClassificationResult {
+  // Hook units default to light
+  if (unitType.startsWith("hook/")) {
+    return applyBudgetPressure({ tier: "light", reason: "hook unit", downgraded: false }, budgetPct);
+  }
+
+  // Triage/capture units default to light
+  if (unitType === "triage-captures" || unitType.startsWith("quick-task")) {
+    return applyBudgetPressure({ tier: "light", reason: `${unitType} unit`, downgraded: false }, budgetPct);
+  }
+
+  let tier = UNIT_TYPE_TIERS[unitType] ?? "standard";
+  let reason = `unit type: ${unitType}`;
+
+  // For execute-task, analyze task metadata for complexity signals
+  if (unitType === "execute-task") {
+    const analysis = analyzeTaskFromPlan(unitId, basePath, metadata);
+    if (analysis) {
+      tier = analysis.tier;
+      reason = analysis.reason;
+    }
+  }
+
+  return applyBudgetPressure({ tier, reason, downgraded: false }, budgetPct);
+}
+
+// ─── Tier Helpers ─────────────────────────────────────────────────────────
+
+export function tierLabel(tier: ComplexityTier): string {
+  switch (tier) {
+    case "light": return "L";
+    case "standard": return "S";
+    case "heavy": return "H";
+  }
+}
+
+export function tierOrdinal(tier: ComplexityTier): number {
+  switch (tier) {
+    case "light": return 0;
+    case "standard": return 1;
+    case "heavy": return 2;
+  }
+}
+
+export function escalateTier(currentTier: ComplexityTier): ComplexityTier | null {
+  switch (currentTier) {
+    case "light": return "standard";
+    case "standard": return "heavy";
+    case "heavy": return null;
+  }
+}
+
+// ─── Budget Pressure (from #579 — graduated thresholds) ───────────────────
+
+function applyBudgetPressure(
+  result: ClassificationResult,
+  budgetPct?: number,
+): ClassificationResult {
+  if (budgetPct === undefined || budgetPct < 0.5) return result;
+
+  const original = result.tier;
+
+  if (budgetPct >= 0.9) {
+    // >90%: almost everything goes to light
+    if (result.tier !== "heavy") {
+      result.tier = "light";
+    } else {
+      result.tier = "standard";
+    }
+  } else if (budgetPct >= 0.75) {
+    // 75-90%: only heavy stays, standard → light
+    if (result.tier === "standard") {
+      result.tier = "light";
+    }
+  } else {
+    // 50-75%: standard → light
+    if (result.tier === "standard") {
+      result.tier = "light";
+    }
+  }
+
+  if (result.tier !== original) {
+    result.downgraded = true;
+    result.reason = `${result.reason} (budget pressure: ${Math.round(budgetPct * 100)}%)`;
+  }
+
+  return result;
+}
+
+// ─── Task Plan Analysis ───────────────────────────────────────────────────
+
+interface TaskAnalysis {
+  tier: ComplexityTier;
+  reason: string;
+}
+
+function analyzeTaskFromPlan(
+  unitId: string,
+  basePath: string,
+  metadata?: TaskMetadata,
+): TaskAnalysis | null {
+  // Try to read the task plan for analysis
+  const parts = unitId.split("/");
+  if (parts.length < 3) return null;
+
+  const [mid, sid, tid] = parts;
+  const planPath = join(basePath, ".gsd", "milestones", mid, "slices", sid, "tasks", `${tid}-PLAN.md`);
+
+  let planContent = "";
+  try {
+    if (existsSync(planPath)) {
+      planContent = readFileSync(planPath, "utf-8");
+    }
+  } catch {
+    return null;
+  }
+
+  if (!planContent) return null;
+
+  const taskComplexity = classifyTaskComplexity(planContent);
+
+  // Map TaskComplexity to ComplexityTier
+  switch (taskComplexity) {
+    case "simple": return { tier: "light", reason: "task plan: simple (few steps, small scope)" };
+    case "complex": return { tier: "heavy", reason: "task plan: complex (many steps/files or signal words)" };
+    default: return { tier: "standard", reason: "task plan: standard complexity" };
+  }
+}

package/dist/resources/extensions/gsd/docs/preferences-reference.md

@@ -108,6 +108,7 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `pre_merge_check`: boolean or `"auto"` — run pre-merge checks before merging a worktree back to the integration branch. `true` always runs, `false` never runs, `"auto"` runs when CI is detected. Default: `false`.
   - `commit_type`: string — override the conventional commit type prefix. Must be one of: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `ci`, `build`, `style`. Default: inferred from diff content.
   - `main_branch`: string — the primary branch name for new git repos (e.g., `"main"`, `"master"`, `"trunk"`). Also used by `getMainBranch()` as the preferred branch when auto-detection is ambiguous. Default: `"main"`.
+  - `commit_docs`: boolean — when `false`, prevents GSD from committing `.gsd/` planning artifacts to git. The `.gsd/` folder is added to `.gitignore` and kept local-only. Useful for teams where only some members use GSD, or when company policy requires a clean repository. Default: `true`.
 
 - `unique_milestone_ids`: boolean — when `true`, generates milestone IDs in `M{seq}-{rand6}` format (e.g. `M001-eh88as`) instead of plain sequential `M001`. Prevents ID collisions in team workflows where multiple contributors create milestones concurrently. Both formats coexist — existing `M001`-style milestones remain valid. Default: `false`.
 

package/dist/resources/extensions/gsd/files.ts

@@ -26,12 +26,16 @@ import { nativeParseRoadmap, nativeExtractSection, nativeParsePlanFile, nativePa
 
 const CACHE_MAX = 50;
 
-/** Fast composite key: length + first/last 100 chars. Unique enough for distinct markdown files. */
+/** Fast composite key: length + first/mid/last 100 chars. The middle sample
+ *  prevents collisions when only a few characters change in the interior of
+ *  a file (e.g., a checkbox [ ] → [x] that doesn't alter length or endpoints). */
 function cacheKey(content: string): string {
   const len = content.length;
   const head = content.slice(0, 100);
+  const midStart = Math.max(0, Math.floor(len / 2) - 50);
+  const mid = len > 200 ? content.slice(midStart, midStart + 100) : '';
   const tail = len > 100 ? content.slice(-100) : '';
-  return `${len}:${head}:${tail}`;
+  return `${len}:${head}:${mid}:${tail}`;
 }
 
 const _parseCache = new Map<string, unknown>();

package/dist/resources/extensions/gsd/git-service.ts

@@ -47,6 +47,11 @@ export interface GitPreferences {
    *  - "branch": works directly in the project root (for submodule-heavy repos)
    */
   isolation?: "worktree" | "branch";
+  /** When false, prevents GSD from committing .gsd/ planning artifacts to git.
+   *  The .gsd/ folder is added to .gitignore and kept local-only.
+   *  Default: true (planning docs are tracked in git).
+   */
+  commit_docs?: boolean;
 }
 
 export const VALID_BRANCH_NAME = /^[a-zA-Z0-9_\-\/.]+$/;
@@ -152,7 +157,7 @@ export function readIntegrationBranch(basePath: string, milestoneId: string): st
  *
  * The file is committed immediately so the metadata is persisted in git.
  */
-export function writeIntegrationBranch(basePath: string, milestoneId: string, branch: string): void {
+export function writeIntegrationBranch(basePath: string, milestoneId: string, branch: string, options?: { commitDocs?: boolean }): void {
   // Don't record slice branches as the integration target
   if (SLICE_BRANCH_RE.test(branch)) return;
   // Validate
@@ -178,12 +183,15 @@ export function writeIntegrationBranch(basePath: string, milestoneId: string, br
   writeFileSync(metaFile, JSON.stringify(existing, null, 2) + "\n", "utf-8");
 
   // Commit immediately so the metadata is persisted in git.
-  try {
-    nativeAddPaths(basePath, [metaFile]);
-    nativeCommit(basePath, `chore(${milestoneId}): record integration branch`, { allowEmpty: false });
-  } catch {
-    // Non-fatal — file is on disk even if commit fails (e.g. nothing to commit
-    // because the file was already tracked with identical content)
+  // Skip when commit_docs is explicitly false — .gsd/ is local-only.
+  if (options?.commitDocs !== false) {
+    try {
+      nativeAddPaths(basePath, [metaFile]);
+      nativeCommit(basePath, `chore(${milestoneId}): record integration branch`, { allowEmpty: false });
+    } catch {
+      // Non-fatal — file is on disk even if commit fails (e.g. nothing to commit
+      // because the file was already tracked with identical content)
+    }
   }
 }
 
@@ -284,7 +292,10 @@ export class GitServiceImpl {
    * @param extraExclusions Additional pathspec exclusions beyond RUNTIME_EXCLUSION_PATHS.
    */
   private smartStage(extraExclusions: readonly string[] = []): void {
-    const allExclusions = [...RUNTIME_EXCLUSION_PATHS, ...extraExclusions];
+    // When commit_docs is false, exclude the entire .gsd/ directory from staging
+    const commitDocsDisabled = this.prefs.commit_docs === false;
+    const gsdExclusion = commitDocsDisabled ? [".gsd/"] : [];
+    const allExclusions = [...RUNTIME_EXCLUSION_PATHS, ...gsdExclusion, ...extraExclusions];
 
     // One-time cleanup: if runtime files are already tracked in the index
     // (from older versions where the fallback bug staged them), untrack them

package/dist/resources/extensions/gsd/gitignore.ts

@@ -78,15 +78,26 @@ const BASELINE_PATTERNS = [
  * Ensure basePath/.gitignore contains all baseline patterns.
  * Creates the file if missing; appends only missing lines if it exists.
  * Returns true if the file was created or modified, false if already complete.
+ *
+ * When `commitDocs` is false, the entire `.gsd/` directory is added to
+ * .gitignore instead of individual runtime patterns, keeping all GSD
+ * artifacts local-only.
  */
-export function ensureGitignore(basePath: string): boolean {
+export function ensureGitignore(basePath: string, options?: { commitDocs?: boolean }): boolean {
   const gitignorePath = join(basePath, ".gitignore");
+  const commitDocs = options?.commitDocs !== false; // default true
 
   let existing = "";
   if (existsSync(gitignorePath)) {
     existing = readFileSync(gitignorePath, "utf-8");
   }
 
+  // When commit_docs is false, ensure blanket ".gsd/" is in .gitignore
+  // and skip the self-heal that would remove it.
+  if (!commitDocs) {
+    return ensureBlanketGsdIgnore(gitignorePath, existing);
+  }
+
   // Self-heal: remove blanket ".gsd/" lines from pre-v2.14.0 projects.
   // The blanket ignore prevented planning artifacts (.gsd/milestones/) from
   // being tracked in git, causing artifacts to vanish in worktrees and
@@ -203,7 +214,7 @@ See \`~/.gsd/agent/extensions/gsd/docs/preferences-reference.md\` for full field
 - \`models\`: Model preferences for specific task types
 - \`skill_discovery\`: Automatic skill detection preferences
 - \`auto_supervisor\`: Supervision and gating rules for autonomous modes
-- \`git\`: Git preferences — \`main_branch\` (default branch name for new repos, e.g., "main", "master", "trunk"), \`auto_push\`, \`snapshots\`, etc.
+- \`git\`: Git preferences — \`main_branch\` (default branch name for new repos, e.g., "main", "master", "trunk"), \`auto_push\`, \`snapshots\`, \`commit_docs\` (set to \`false\` to keep .gsd/ local-only), etc.
 
 ## Examples
 
@@ -224,3 +235,31 @@ custom_instructions:
   return true;
 }
 
+/**
+ * When commit_docs is false, ensure `.gsd/` is in .gitignore as a blanket
+ * pattern. This keeps all GSD artifacts local-only.
+ * Returns true if the file was modified, false if already complete.
+ */
+function ensureBlanketGsdIgnore(gitignorePath: string, existing: string): boolean {
+  const existingLines = new Set(
+    existing
+      .split("\n")
+      .map((l) => l.trim())
+      .filter((l) => l && !l.startsWith("#")),
+  );
+
+  // Already has blanket .gsd/ ignore
+  if (existingLines.has(".gsd/") || existingLines.has(".gsd")) return false;
+
+  const block = [
+    "",
+    "# ── GSD (local-only, commit_docs: false) ──",
+    ".gsd/",
+    "",
+  ].join("\n");
+
+  const prefix = existing && !existing.endsWith("\n") ? "\n" : "";
+  writeFileSync(gitignorePath, existing + prefix + block, "utf-8");
+  return true;
+}
+

package/dist/resources/extensions/gsd/guided-flow.ts

@@ -712,7 +712,8 @@ export async function showSmartEntry(
   }
 
   // ── Ensure .gitignore has baseline patterns ──────────────────────────
-  ensureGitignore(basePath);
+  const commitDocs = loadEffectiveGSDPreferences()?.preferences?.git?.commit_docs;
+  ensureGitignore(basePath, { commitDocs });
   untrackRuntimeFiles(basePath);
 
   // ── No GSD project OR no milestone → Create first/next milestone ────
@@ -723,11 +724,14 @@ export async function showSmartEntry(
 
     // ── Create PREFERENCES.md template ────────────────────────────────
     ensurePreferences(basePath);
-    try {
-      nativeAddPaths(basePath, [".gsd", ".gitignore"]);
-      nativeCommit(basePath, "chore: init gsd");
-    } catch {
-      // nothing to commit — that's fine
+    // Only commit .gsd/ init when commit_docs is not explicitly false
+    if (commitDocs !== false) {
+      try {
+        nativeAddPaths(basePath, [".gsd", ".gitignore"]);
+        nativeCommit(basePath, "chore: init gsd");
+      } catch {
+        // nothing to commit — that's fine
+      }
     }
   }
 

package/dist/resources/extensions/gsd/metrics.ts

@@ -303,6 +303,50 @@ export function formatCost(cost: number): string {
   return `$${n.toFixed(2)}`;
 }
 
+// ─── Budget Prediction ────────────────────────────────────────────────────────
+
+/**
+ * Calculate average cost per unit type from completed units.
+ * Returns a Map from unit type to average cost in USD.
+ */
+export function getAverageCostPerUnitType(units: UnitMetrics[]): Map<string, number> {
+  const sums = new Map<string, { total: number; count: number }>();
+  for (const u of units) {
+    const entry = sums.get(u.type) ?? { total: 0, count: 0 };
+    entry.total += u.cost;
+    entry.count += 1;
+    sums.set(u.type, entry);
+  }
+  const avgs = new Map<string, number>();
+  for (const [type, { total, count }] of sums) {
+    avgs.set(type, total / count);
+  }
+  return avgs;
+}
+
+/**
+ * Estimate remaining cost given average costs and remaining unit counts.
+ * @param avgCosts - Average cost per unit type
+ * @param remainingUnits - Array of unit types still to dispatch
+ * @param fallbackAvg - Fallback average if unit type not seen before
+ * @returns Estimated remaining cost in USD
+ */
+export function predictRemainingCost(
+  avgCosts: Map<string, number>,
+  remainingUnits: string[],
+  fallbackAvg?: number,
+): number {
+  // If no averages available, use overall average as fallback
+  const allAvgs = [...avgCosts.values()];
+  const overallAvg = fallbackAvg ?? (allAvgs.length > 0 ? allAvgs.reduce((a, b) => a + b, 0) / allAvgs.length : 0);
+
+  let total = 0;
+  for (const unitType of remainingUnits) {
+    total += avgCosts.get(unitType) ?? overallAvg;
+  }
+  return total;
+}
+
 /**
  * Compute a projected remaining cost based on completed slice averages.
  *

package/dist/resources/extensions/gsd/native-git-bridge.ts

@@ -17,6 +17,10 @@ const GIT_NO_PROMPT_ENV = {
   GIT_SVN_ID: "",
 };
 
+// Issue #453: keep auto-mode bookkeeping on the stable git CLI path unless a
+// caller explicitly opts into the native helper.
+const NATIVE_GSD_GIT_ENABLED = process.env.GSD_ENABLE_NATIVE_GSD_GIT === "1";
+
 // ─── Native Module Types ──────────────────────────────────────────────────
 
 interface GitDiffStat {
@@ -116,6 +120,7 @@ let loadAttempted = false;
 function loadNative(): typeof nativeModule {
   if (loadAttempted) return nativeModule;
   loadAttempted = true;
+  if (!NATIVE_GSD_GIT_ENABLED) return nativeModule;
 
   try {
     // eslint-disable-next-line @typescript-eslint/no-require-imports

package/dist/resources/extensions/gsd/native-parser-bridge.ts

@@ -6,6 +6,10 @@
 
 import type { Roadmap, BoundaryMapEntry, RoadmapSliceEntry, RiskLevel } from './types.js';
 
+// Issue #453: auto-mode post-turn reconciliation must stay on the stable JS path
+// unless the native parser is explicitly requested.
+const NATIVE_GSD_PARSER_ENABLED = process.env.GSD_ENABLE_NATIVE_GSD_PARSER === "1";
+
 let nativeModule: {
   parseFrontmatter: (content: string) => { metadata: string; body: string };
   extractSection: (content: string, heading: string, level?: number) => { content: string; found: boolean };
@@ -29,6 +33,7 @@ let loadAttempted = false;
 function loadNative(): typeof nativeModule {
   if (loadAttempted) return nativeModule;
   loadAttempted = true;
+  if (!NATIVE_GSD_PARSER_ENABLED) return nativeModule;
 
   try {
     // Dynamic import to avoid hard dependency - fails gracefully if native module not built