gsd-pi 2.16.0 → 2.18.0

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

@@ -12,7 +12,8 @@ import { fileURLToPath } from "node:url";
 import { deriveState } from "./state.js";
 import { GSDDashboardOverlay } from "./dashboard-overlay.js";
 import { showQueue, showDiscuss } from "./guided-flow.js";
-import { startAuto, stopAuto, pauseAuto, isAutoActive, isAutoPaused, isStepMode } from "./auto.js";
+import { startAuto, stopAuto, pauseAuto, isAutoActive, isAutoPaused, isStepMode, stopAutoRemote } from "./auto.js";
+import { resolveProjectRoot } from "./worktree.js";
 import {
   getGlobalGSDPreferencesPath,
   getLegacyGlobalGSDPreferencesPath,
@@ -22,7 +23,7 @@ import {
   loadEffectiveGSDPreferences,
   resolveAllSkillReferences,
 } from "./preferences.js";
-import { loadFile, saveFile, appendOverride } from "./files.js";
+import { loadFile, saveFile, appendOverride, appendKnowledge } from "./files.js";
 import {
   formatDoctorIssuesForPrompt,
   formatDoctorReport,
@@ -56,14 +57,19 @@ function dispatchDoctorHeal(pi: ExtensionAPI, scope: string | undefined, reportT
   );
 }
 
+/** Resolve the effective project root, accounting for worktree paths. */
+function projectRoot(): string {
+  return resolveProjectRoot(process.cwd());
+}
+
 export function registerGSDCommand(pi: ExtensionAPI): void {
   pi.registerCommand("gsd", {
-    description: "GSD — Get Shit Done: /gsd next|auto|stop|pause|status|queue|history|undo|skip|export|cleanup|prefs|config|hooks|doctor|migrate|remote|steer",
+    description: "GSD — Get Shit Done: /gsd next|auto|stop|pause|status|queue|history|undo|skip|export|cleanup|prefs|config|hooks|doctor|migrate|remote|steer|knowledge",
     getArgumentCompletions: (prefix: string) => {
       const subcommands = [
         "next", "auto", "stop", "pause", "status", "queue", "discuss",
         "history", "undo", "skip", "export", "cleanup", "prefs",
-        "config", "hooks", "doctor", "migrate", "remote", "steer",
+        "config", "hooks", "doctor", "migrate", "remote", "steer", "knowledge",
       ];
       const parts = prefix.trim().split(/\s+/);
 
@@ -126,6 +132,13 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
           .map((cmd) => ({ value: `cleanup ${cmd}`, label: cmd }));
       }
 
+      if (parts[0] === "knowledge" && parts.length <= 2) {
+        const subPrefix = parts[1] ?? "";
+        return ["rule", "pattern", "lesson"]
+          .filter((cmd) => cmd.startsWith(subPrefix))
+          .map((cmd) => ({ value: `knowledge ${cmd}`, label: cmd }));
+      }
+
       if (parts[0] === "doctor") {
         const modePrefix = parts[1] ?? "";
         const modes = ["fix", "heal", "audit"];
@@ -162,23 +175,31 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
 
       if (trimmed === "next" || trimmed.startsWith("next ")) {
         if (trimmed.includes("--dry-run")) {
-          await handleDryRun(ctx, process.cwd());
+          await handleDryRun(ctx, projectRoot());
           return;
         }
         const verboseMode = trimmed.includes("--verbose");
-        await startAuto(ctx, pi, process.cwd(), verboseMode, { step: true });
+        await startAuto(ctx, pi, projectRoot(), verboseMode, { step: true });
         return;
       }
 
       if (trimmed === "auto" || trimmed.startsWith("auto ")) {
         const verboseMode = trimmed.includes("--verbose");
-        await startAuto(ctx, pi, process.cwd(), verboseMode);
+        await startAuto(ctx, pi, projectRoot(), verboseMode);
         return;
       }
 
       if (trimmed === "stop") {
         if (!isAutoActive() && !isAutoPaused()) {
-          ctx.ui.notify("Auto-mode is not running.", "info");
+          // Not running in this process — check for a remote auto-mode session
+          const result = stopAutoRemote(projectRoot());
+          if (result.found) {
+            ctx.ui.notify(`Sent stop signal to auto-mode session (PID ${result.pid}). It will shut down gracefully.`, "info");
+          } else if (result.error) {
+            ctx.ui.notify(`Failed to stop remote auto-mode: ${result.error}`, "error");
+          } else {
+            ctx.ui.notify("Auto-mode is not running.", "info");
+          }
           return;
         }
         await stopAuto(ctx, pi);
@@ -199,42 +220,42 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
       }
 
       if (trimmed === "history" || trimmed.startsWith("history ")) {
-        await handleHistory(trimmed.replace(/^history\s*/, "").trim(), ctx, process.cwd());
+        await handleHistory(trimmed.replace(/^history\s*/, "").trim(), ctx, projectRoot());
         return;
       }
 
       if (trimmed === "undo" || trimmed.startsWith("undo ")) {
-        await handleUndo(trimmed.replace(/^undo\s*/, "").trim(), ctx, pi, process.cwd());
+        await handleUndo(trimmed.replace(/^undo\s*/, "").trim(), ctx, pi, projectRoot());
         return;
       }
 
       if (trimmed.startsWith("skip ")) {
-        await handleSkip(trimmed.replace(/^skip\s*/, "").trim(), ctx, process.cwd());
+        await handleSkip(trimmed.replace(/^skip\s*/, "").trim(), ctx, projectRoot());
         return;
       }
 
       if (trimmed === "export" || trimmed.startsWith("export ")) {
-        await handleExport(trimmed.replace(/^export\s*/, "").trim(), ctx, process.cwd());
+        await handleExport(trimmed.replace(/^export\s*/, "").trim(), ctx, projectRoot());
         return;
       }
 
       if (trimmed === "cleanup branches") {
-        await handleCleanupBranches(ctx, process.cwd());
+        await handleCleanupBranches(ctx, projectRoot());
         return;
       }
 
       if (trimmed === "cleanup snapshots") {
-        await handleCleanupSnapshots(ctx, process.cwd());
+        await handleCleanupSnapshots(ctx, projectRoot());
         return;
       }
 
       if (trimmed === "queue") {
-        await showQueue(ctx, pi, process.cwd());
+        await showQueue(ctx, pi, projectRoot());
         return;
       }
 
       if (trimmed === "discuss") {
-        await showDiscuss(ctx, pi, process.cwd());
+        await showDiscuss(ctx, pi, projectRoot());
         return;
       }
 
@@ -258,6 +279,15 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
         return;
       }
 
+      if (trimmed.startsWith("knowledge ")) {
+        await handleKnowledge(trimmed.replace(/^knowledge\s+/, "").trim(), ctx);
+        return;
+      }
+      if (trimmed === "knowledge") {
+        ctx.ui.notify("Usage: /gsd knowledge <rule|pattern|lesson> <description>. Example: /gsd knowledge rule Use real DB for integration tests", "warning");
+        return;
+      }
+
       if (trimmed === "migrate" || trimmed.startsWith("migrate ")) {
         const { handleMigrate } = await import("./migrate/command.js");
         await handleMigrate(trimmed.replace(/^migrate\s*/, "").trim(), ctx, pi);
@@ -271,12 +301,12 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
 
       if (trimmed === "") {
         // Bare /gsd defaults to step mode
-        await startAuto(ctx, pi, process.cwd(), false, { step: true });
+        await startAuto(ctx, pi, projectRoot(), false, { step: true });
         return;
       }
 
       ctx.ui.notify(
-        `Unknown: /gsd ${trimmed}. Use /gsd next|auto|stop|pause|status|queue|discuss|history|undo|skip <unit>|export|cleanup|prefs|config|hooks|doctor|migrate|remote|steer <change>.`,
+        `Unknown: /gsd ${trimmed}. Use /gsd next|auto|stop|pause|status|queue|discuss|history|undo|skip <unit>|export|cleanup|prefs|config|hooks|doctor|migrate|remote|steer <change>|knowledge <type> <entry>.`,
         "warning",
       );
     },
@@ -284,7 +314,7 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
 }
 
 async function handleStatus(ctx: ExtensionCommandContext): Promise<void> {
-  const basePath = process.cwd();
+  const basePath = projectRoot();
   const state = await deriveState(basePath);
 
   if (state.registry.length === 0) {
@@ -368,9 +398,9 @@ async function handleDoctor(args: string, ctx: ExtensionCommandContext, pi: Exte
   const parts = trimmed ? trimmed.split(/\s+/) : [];
   const mode = parts[0] === "fix" || parts[0] === "heal" || parts[0] === "audit" ? parts[0] : "doctor";
   const requestedScope = mode === "doctor" ? parts[0] : parts[1];
-  const scope = await selectDoctorScope(process.cwd(), requestedScope);
+  const scope = await selectDoctorScope(projectRoot(), requestedScope);
   const effectiveScope = mode === "audit" ? requestedScope : scope;
-  const report = await runGSDDoctor(process.cwd(), {
+  const report = await runGSDDoctor(projectRoot(), {
     fix: mode === "fix" || mode === "heal",
     scope: effectiveScope,
   });
@@ -487,8 +517,10 @@ async function handlePrefsWizard(
     prefs.auto_supervisor = autoSup;
   }
 
-  // ─── Git main branch ────────────────────────────────────────────────────
+  // ─── Git settings ───────────────────────────────────────────────────────
   const git: Record<string, unknown> = (prefs.git as Record<string, unknown>) ?? {};
+
+  // main_branch
   const currentBranch = git.main_branch ? String(git.main_branch) : "";
   const branchInput = await ctx.ui.input(
     `Git main branch${currentBranch ? ` (current: ${currentBranch})` : ""}:`,
@@ -502,6 +534,100 @@ async function handlePrefsWizard(
       delete git.main_branch;
     }
   }
+
+  // Boolean git toggles
+  const gitBooleanFields = [
+    { key: "auto_push", label: "Auto-push commits after committing", defaultVal: false },
+    { key: "push_branches", label: "Push milestone branches to remote", defaultVal: false },
+    { key: "snapshots", label: "Create WIP snapshot commits during long tasks", defaultVal: false },
+  ] as const;
+
+  for (const field of gitBooleanFields) {
+    const current = git[field.key];
+    const currentStr = current !== undefined ? String(current) : "";
+    const choice = await ctx.ui.select(
+      `${field.label}${currentStr ? ` (current: ${currentStr})` : ` (default: ${field.defaultVal})`}:`,
+      ["true", "false", "(keep current)"],
+    );
+    if (choice && choice !== "(keep current)") {
+      git[field.key] = choice === "true";
+    }
+  }
+
+  // remote
+  const currentRemote = git.remote ? String(git.remote) : "";
+  const remoteInput = await ctx.ui.input(
+    `Git remote name${currentRemote ? ` (current: ${currentRemote})` : " (default: origin)"}:`,
+    currentRemote || "origin",
+  );
+  if (remoteInput !== null && remoteInput !== undefined) {
+    const val = remoteInput.trim();
+    if (val && val !== "origin") {
+      git.remote = val;
+    } else if (!val && currentRemote) {
+      delete git.remote;
+    }
+  }
+
+  // pre_merge_check
+  const currentPreMerge = git.pre_merge_check !== undefined ? String(git.pre_merge_check) : "";
+  const preMergeChoice = await ctx.ui.select(
+    `Pre-merge check${currentPreMerge ? ` (current: ${currentPreMerge})` : " (default: false)"}:`,
+    ["true", "false", "auto", "(keep current)"],
+  );
+  if (preMergeChoice && preMergeChoice !== "(keep current)") {
+    if (preMergeChoice === "auto") {
+      git.pre_merge_check = "auto";
+    } else {
+      git.pre_merge_check = preMergeChoice === "true";
+    }
+  }
+
+  // commit_type
+  const currentCommitType = git.commit_type ? String(git.commit_type) : "";
+  const commitTypes = ["feat", "fix", "refactor", "docs", "test", "chore", "perf", "ci", "build", "style", "(inferred — default)", "(keep current)"];
+  const commitChoice = await ctx.ui.select(
+    `Default commit type${currentCommitType ? ` (current: ${currentCommitType})` : ""}:`,
+    commitTypes,
+  );
+  if (commitChoice && typeof commitChoice === "string" && commitChoice !== "(keep current)") {
+    if ((commitChoice as string).startsWith("(inferred")) {
+      delete git.commit_type;
+    } else {
+      git.commit_type = commitChoice;
+    }
+  }
+
+  // merge_strategy
+  const currentMerge = git.merge_strategy ? String(git.merge_strategy) : "";
+  const mergeChoice = await ctx.ui.select(
+    `Merge strategy${currentMerge ? ` (current: ${currentMerge})` : ""}:`,
+    ["squash", "merge", "(keep current)"],
+  );
+  if (mergeChoice && mergeChoice !== "(keep current)") {
+    git.merge_strategy = mergeChoice;
+  }
+
+  // isolation
+  const currentIsolation = git.isolation ? String(git.isolation) : "";
+  const isolationChoice = await ctx.ui.select(
+    `Git isolation strategy${currentIsolation ? ` (current: ${currentIsolation})` : " (default: worktree)"}:`,
+    ["worktree", "branch", "(keep current)"],
+  );
+  if (isolationChoice && isolationChoice !== "(keep current)") {
+    git.isolation = isolationChoice;
+  }
+
+  // ─── Git commit_docs ────────────────────────────────────────────────────
+  const currentCommitDocs = git.commit_docs;
+  const commitDocsChoice = await ctx.ui.select(
+    `Track .gsd/ planning docs in git${currentCommitDocs !== undefined ? ` (current: ${currentCommitDocs})` : ""}:`,
+    ["true", "false", "(keep current)"],
+  );
+  if (commitDocsChoice && commitDocsChoice !== "(keep current)") {
+    git.commit_docs = commitDocsChoice === "true";
+  }
+
   if (Object.keys(git).length > 0) {
     prefs.git = git;
   }
@@ -526,6 +652,89 @@ async function handlePrefsWizard(
     prefs.unique_milestone_ids = uniqueChoice === "true";
   }
 
+  // ─── Budget & cost control ────────────────────────────────────────────
+  const currentCeiling = prefs.budget_ceiling;
+  const ceilingStr = currentCeiling !== undefined ? String(currentCeiling) : "";
+  const ceilingInput = await ctx.ui.input(
+    `Budget ceiling (USD)${ceilingStr ? ` (current: $${ceilingStr})` : " (default: no limit)"}:`,
+    ceilingStr || "",
+  );
+  if (ceilingInput !== null && ceilingInput !== undefined) {
+    const val = ceilingInput.trim().replace(/^\$/, "");
+    if (val && !isNaN(Number(val)) && isFinite(Number(val))) {
+      prefs.budget_ceiling = Number(val);
+    } else if (val && (isNaN(Number(val)) || !isFinite(Number(val)))) {
+      ctx.ui.notify(`Invalid budget ceiling "${val}" — must be a number. Keeping previous value.`, "warning");
+    } else if (!val && ceilingStr) {
+      delete prefs.budget_ceiling;
+    }
+  }
+
+  const currentEnforcement = (prefs.budget_enforcement as string) ?? "";
+  const enforcementChoice = await ctx.ui.select(
+    `Budget enforcement${currentEnforcement ? ` (current: ${currentEnforcement})` : " (default: pause)"}:`,
+    ["warn", "pause", "halt", "(keep current)"],
+  );
+  if (enforcementChoice && enforcementChoice !== "(keep current)") {
+    prefs.budget_enforcement = enforcementChoice;
+  }
+
+  const currentContextPause = prefs.context_pause_threshold;
+  const contextPauseStr = currentContextPause !== undefined ? String(currentContextPause) : "";
+  const contextPauseInput = await ctx.ui.input(
+    `Context pause threshold (0-100%, 0=disabled)${contextPauseStr ? ` (current: ${contextPauseStr}%)` : " (default: 0)"}:`,
+    contextPauseStr || "0",
+  );
+  if (contextPauseInput !== null && contextPauseInput !== undefined) {
+    const val = contextPauseInput.trim().replace(/%$/, "");
+    if (val && !isNaN(Number(val)) && Number(val) >= 0 && Number(val) <= 100) {
+      const num = Number(val);
+      if (num === 0) {
+        delete prefs.context_pause_threshold;
+      } else {
+        prefs.context_pause_threshold = num;
+      }
+    } else if (val && (isNaN(Number(val)) || Number(val) < 0 || Number(val) > 100)) {
+      ctx.ui.notify(`Invalid context pause threshold "${val}" — must be 0-100. Keeping previous value.`, "warning");
+    }
+  }
+
+  // ─── Notifications ────────────────────────────────────────────────────
+  const notif: Record<string, boolean> = (prefs.notifications as Record<string, boolean>) ?? {};
+  const notifFields = [
+    { key: "enabled", label: "Notifications enabled (master toggle)", defaultVal: true },
+    { key: "on_complete", label: "Notify on unit completion", defaultVal: true },
+    { key: "on_error", label: "Notify on errors", defaultVal: true },
+    { key: "on_budget", label: "Notify on budget thresholds", defaultVal: true },
+    { key: "on_milestone", label: "Notify on milestone completion", defaultVal: true },
+    { key: "on_attention", label: "Notify when manual attention needed", defaultVal: true },
+  ] as const;
+
+  for (const field of notifFields) {
+    const current = notif[field.key];
+    const currentStr = current !== undefined ? String(current) : "";
+    const choice = await ctx.ui.select(
+      `${field.label}${currentStr ? ` (current: ${currentStr})` : ` (default: ${field.defaultVal})`}:`,
+      ["true", "false", "(keep current)"],
+    );
+    if (choice && choice !== "(keep current)") {
+      notif[field.key] = choice === "true";
+    }
+  }
+  if (Object.keys(notif).length > 0) {
+    prefs.notifications = notif;
+  }
+
+  // ─── UAT dispatch ─────────────────────────────────────────────────────
+  const currentUat = prefs.uat_dispatch;
+  const uatChoice = await ctx.ui.select(
+    `UAT dispatch mode${currentUat !== undefined ? ` (current: ${currentUat})` : " (default: false)"}:`,
+    ["true", "false", "(keep current)"],
+  );
+  if (uatChoice && uatChoice !== "(keep current)") {
+    prefs.uat_dispatch = uatChoice === "true";
+  }
+
   // ─── Serialize to frontmatter ───────────────────────────────────────────
   prefs.version = prefs.version || 1;
   const frontmatter = serializePreferencesToFrontmatter(prefs);
@@ -616,7 +825,10 @@ function serializePreferencesToFrontmatter(prefs: Record<string, unknown>): stri
   const orderedKeys = [
     "version", "always_use_skills", "prefer_skills", "avoid_skills",
     "skill_rules", "custom_instructions", "models", "skill_discovery",
-    "auto_supervisor", "uat_dispatch", "unique_milestone_ids", "budget_ceiling", "remote_questions", "git",
+    "auto_supervisor", "uat_dispatch", "unique_milestone_ids",
+    "budget_ceiling", "budget_enforcement", "context_pause_threshold",
+    "notifications", "remote_questions", "git",
+    "post_unit_hooks", "pre_dispatch_hooks",
   ];
 
   const seen = new Set<string>();
@@ -954,6 +1166,35 @@ async function handleCleanupSnapshots(ctx: ExtensionCommandContext, basePath: st
   ctx.ui.notify(`Pruned ${pruned} old snapshot refs. ${refs.length - pruned} remain.`, "success");
 }
 
+async function handleKnowledge(args: string, ctx: ExtensionCommandContext): Promise<void> {
+  const parts = args.split(/\s+/);
+  const typeArg = parts[0]?.toLowerCase();
+
+  if (!typeArg || !["rule", "pattern", "lesson"].includes(typeArg)) {
+    ctx.ui.notify(
+      "Usage: /gsd knowledge <rule|pattern|lesson> <description>\nExample: /gsd knowledge rule Use real DB for integration tests",
+      "warning",
+    );
+    return;
+  }
+
+  const entryText = parts.slice(1).join(" ").trim();
+  if (!entryText) {
+    ctx.ui.notify(`Usage: /gsd knowledge ${typeArg} <description>`, "warning");
+    return;
+  }
+
+  const type = typeArg as "rule" | "pattern" | "lesson";
+  const basePath = process.cwd();
+  const state = await deriveState(basePath);
+  const scope = state.activeMilestone?.id
+    ? `${state.activeMilestone.id}${state.activeSlice ? `/${state.activeSlice.id}` : ""}`
+    : "global";
+
+  await appendKnowledge(basePath, type, entryText, scope);
+  ctx.ui.notify(`Added ${type} to KNOWLEDGE.md: "${entryText}"`, "success");
+}
+
 async function handleSteer(change: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {
   const basePath = process.cwd();
   const state = await deriveState(basePath);

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" };
+  }
+}