@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.eed73bea

package/src/resources/extensions/gsd/post-execution-checks.ts

@@ -16,7 +16,7 @@
  *   - No AST parsers — uses regex heuristics
  */
 
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { resolve, dirname, join, extname } from "node:path";
 import type { TaskRow } from "./db-task-slice-rows.js";
 
@@ -364,6 +364,15 @@ interface FunctionSignature {
   lineNum: number;
 }
 
+interface CachedFunctionSignatures {
+  mtimeMs: number;
+  size: number;
+  signatures: FunctionSignature[];
+}
+
+let signatureCacheScope: string | null = null;
+const signatureCache = new Map<string, CachedFunctionSignatures>();
+
 /**
  * Extract function signatures from TypeScript/JavaScript source code.
  */
@@ -404,6 +413,37 @@ function extractFunctionSignatures(
   return signatures;
 }
 
+function signatureCacheFor(taskRow: TaskRow, basePath: string): Map<string, CachedFunctionSignatures> {
+  const scope = `${resolve(basePath)}\0${taskRow.milestone_id}\0${taskRow.slice_id}`;
+
+  if (signatureCacheScope !== scope) {
+    signatureCacheScope = scope;
+    signatureCache.clear();
+  }
+
+  return signatureCache;
+}
+
+function getCachedFunctionSignatures(
+  cache: Map<string, CachedFunctionSignatures>,
+  absolutePath: string,
+  fileName: string
+): FunctionSignature[] {
+  const stat = statSync(absolutePath);
+  const mtimeMs = stat.mtimeMs;
+  const size = stat.size;
+  const cached = cache.get(absolutePath);
+
+  if (cached && cached.mtimeMs === mtimeMs && cached.size === size) {
+    return cached.signatures.map((sig) => ({ ...sig, file: fileName }));
+  }
+
+  const source = readFileSync(absolutePath, "utf-8");
+  const signatures = extractFunctionSignatures(source, fileName);
+  cache.set(absolutePath, { mtimeMs, size, signatures });
+  return signatures;
+}
+
 /**
  * Normalize parameter list for comparison.
  */
@@ -437,6 +477,7 @@ export function checkCrossTaskSignatures(
 
   // Build map of functions from prior tasks' key_files
   const priorSignatures = new Map<string, FunctionSignature[]>();
+  const cache = signatureCacheFor(taskRow, basePath);
 
   for (const task of priorTasks) {
     for (const file of task.key_files) {
@@ -447,8 +488,7 @@ export function checkCrossTaskSignatures(
       if (!existsSync(absolutePath)) continue;
 
       try {
-        const source = readFileSync(absolutePath, "utf-8");
-        const sigs = extractFunctionSignatures(source, file);
+        const sigs = getCachedFunctionSignatures(cache, absolutePath, file);
         for (const sig of sigs) {
           const existing = priorSignatures.get(sig.name) || [];
           existing.push(sig);

package/src/resources/extensions/gsd/pre-execution-checks.ts

@@ -24,6 +24,7 @@ import { isAbsolute, relative, resolve } from "node:path";
 import type { TaskRow } from "./db-task-slice-rows.js";
 import type { PreExecutionCheckJSON } from "./verification-evidence.ts";
 import { validateVerificationCommand } from "./verification-gate.js";
+import { FRAMEWORK_METADATA_DIRS, PLANNING_ARTIFACT_NAME_RE } from "./paths.js";
 
 const NPM_COMMAND = process.platform === "win32" ? "npm.cmd" : "npm";
 
@@ -586,6 +587,9 @@ export function checkFilePathConsistency(
       // Skip empty strings
       if (!file.trim()) continue;
       if (!shouldValidateInputAsPath(file)) continue;
+      // Planning-artifact references are owned by checkPlanningArtifactReferences,
+      // which reports a precise removal message instead of "doesn't exist".
+      if (isPlanningArtifactReference(file, basePath, context)) continue;
 
       // Normalize path for consistent comparison
       const normalizedFile = toComparisonPath(file, basePath);
@@ -628,6 +632,85 @@ export function checkFilePathConsistency(
   return results;
 }
 
+// ─── Planning Artifact Reference Check ───────────────────────────────────────
+
+function isFrameworkMetadataPath(normalizedFile: string): boolean {
+  return normalizedFile.split("/").some((segment) => FRAMEWORK_METADATA_DIRS.includes(segment.toLowerCase()));
+}
+
+/**
+ * True when a task IO entry references a GSD planning artifact.
+ *
+ * Task inputs are source files only — planning artifacts are projections of DB
+ * state that the framework preloads as composed context (see CONTEXT.md "Task
+ * Input"). Two triggers, deliberately different in strictness:
+ *
+ * - Any path entering framework-owned metadata (.gsd/, .planning/, .audits/)
+ *   is always a violation, even when the file exists.
+ * - A bare artifact-style basename (M001-CONTEXT.md, S01-PLAN.md, …) is a
+ *   violation only when it does NOT resolve to a real file. When such a file
+ *   genuinely exists in the source tree (e.g. a fixture), it is a source file
+ *   and stays legal; a path with directory components is likewise left to the
+ *   ordinary existence checks.
+ */
+function isPlanningArtifactReference(
+  rawEntry: string,
+  basePath: string,
+  context?: PreExecutionCheckContext,
+): boolean {
+  if (!shouldValidateInputAsPath(rawEntry)) return false;
+  const normalized = toComparisonPath(rawEntry, basePath);
+  if (isFrameworkMetadataPath(normalized)) return true;
+  return (
+    !normalized.includes("/") &&
+    PLANNING_ARTIFACT_NAME_RE.test(normalized) &&
+    !inputExistsOnDisk(normalized, basePath, context)
+  );
+}
+
+/**
+ * Block GSD planning artifacts in task IO fields (inputs, files, expectedOutput).
+ *
+ * For inputs/files the violation smuggles a projection into the executor's
+ * preloaded source context; for expectedOutput it promises a write the runtime
+ * write-gate would reject mid-execution. Both get a precise message so the
+ * planning retry steers toward *removing* the reference, not creating the file.
+ * checkFilePathConsistency and checkTaskOrdering skip entries this check owns.
+ */
+export function checkPlanningArtifactReferences(
+  tasks: TaskRow[],
+  basePath: string,
+  context?: PreExecutionCheckContext,
+): PreExecutionCheckJSON[] {
+  const results: PreExecutionCheckJSON[] = [];
+
+  for (const task of tasks) {
+    const fields = [
+      { label: "inputs", entries: task.inputs },
+      { label: "files", entries: task.files },
+      { label: "expectedOutput", entries: task.expected_output },
+    ];
+    for (const { label, entries } of fields) {
+      for (const file of entries) {
+        if (!isPlanningArtifactReference(file, basePath, context)) continue;
+        const message =
+          label === "expectedOutput"
+            ? `Task ${task.id} lists '${file}' in expectedOutput — GSD planning artifacts are written by workflow tools (e.g. gsd_summary_save), never by tasks; remove it`
+            : `Task ${task.id} lists '${file}' in ${label} — GSD planning artifacts are projections preloaded as context, never task ${label}; remove it`;
+        results.push({
+          category: "file",
+          target: file,
+          passed: false,
+          message,
+          blocking: true,
+        });
+      }
+    }
+  }
+
+  return results;
+}
+
 // ─── Task Ordering Check ─────────────────────────────────────────────────────
 
 /**
@@ -671,6 +754,9 @@ export function checkTaskOrdering(
     for (const file of filesToCheck) {
       if (isRuntimeOnlyInput(file)) continue;
       if (!shouldValidateInputAsPath(file)) continue;
+      // Owned by checkPlanningArtifactReferences — avoid a duplicate sequence
+      // finding on top of the removal message.
+      if (isPlanningArtifactReference(file, basePath, context)) continue;
 
       const normalizedFile = toComparisonPath(file, basePath);
       if (containsGlobPattern(normalizedFile)) continue;
@@ -700,6 +786,27 @@ export function checkTaskOrdering(
   return results;
 }
 
+// ─── Shared Path-Check Composition ───────────────────────────────────────────
+
+/**
+ * The synchronous path-shaped checks, in order. One list shared by the
+ * plan-persist gate (gsd_plan_slice) and the dispatch gate
+ * (runPreExecutionChecks) so the two cannot drift — the checks coordinate
+ * ownership of planning-artifact entries via isPlanningArtifactReference
+ * skips, which only works when they run as a set.
+ */
+export function runTaskPathChecks(
+  tasks: TaskRow[],
+  basePath: string,
+  context?: PreExecutionCheckContext,
+): PreExecutionCheckJSON[] {
+  return [
+    ...checkPlanningArtifactReferences(tasks, basePath, context),
+    ...checkFilePathConsistency(tasks, basePath, context),
+    ...checkTaskOrdering(tasks, basePath, context),
+  ];
+}
+
 // ─── Interface Contract Check ────────────────────────────────────────────────
 
 interface FunctionSignature {
@@ -866,12 +973,11 @@ export async function runPreExecutionChecks(
   const allChecks: PreExecutionCheckJSON[] = [];
 
   // Run sync checks first
-  const fileChecks = checkFilePathConsistency(tasks, basePath, context);
-  const orderingChecks = checkTaskOrdering(tasks, basePath, context);
+  const pathChecks = runTaskPathChecks(tasks, basePath, context);
   const contractChecks = checkInterfaceContracts(tasks, basePath);
   const verificationChecks = checkVerificationCommands(tasks);
 
-  allChecks.push(...fileChecks, ...orderingChecks, ...contractChecks, ...verificationChecks);
+  allChecks.push(...pathChecks, ...contractChecks, ...verificationChecks);
 
   // Run async package checks
   const packageChecks = await checkPackageExistence(tasks, basePath);

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

@@ -0,0 +1,98 @@
+import type { PreferenceDiagnostic } from "./preferences-types.js";
+import {
+  loadGlobalGSDPreferences,
+  loadProjectGSDPreferences,
+} from "./preferences.js";
+
+interface PreferenceNotificationContext {
+  ui: {
+    notify(message: string, type?: "info" | "warning" | "error" | "success"): void;
+  };
+}
+
+interface PreferenceDiagnosticNotificationOptions {
+  surface?: string;
+}
+
+const notifiedPreferenceDiagnostics = new Set<string>();
+
+export function collectPreferenceDiagnostics(basePath?: string): PreferenceDiagnostic[] {
+  const diagnostics = [
+    ...(loadGlobalGSDPreferences()?.diagnostics ?? []),
+    ...(loadProjectGSDPreferences(basePath)?.diagnostics ?? []),
+  ];
+
+  const seen = new Set<string>();
+  const unique: PreferenceDiagnostic[] = [];
+  for (const diagnostic of diagnostics) {
+    const signature = preferenceDiagnosticSignature(diagnostic);
+    if (seen.has(signature)) continue;
+    seen.add(signature);
+    unique.push(diagnostic);
+  }
+  return unique;
+}
+
+export function formatPreferenceDiagnostic(diagnostic: PreferenceDiagnostic): string {
+  const scope = diagnostic.scope === "global" ? "global" : "project";
+  const level = diagnostic.severity === "error" ? "error" : "warning";
+  const heading = diagnostic.kind === "parse"
+    ? `GSD ${scope} preferences ${level}: ${diagnostic.path} could not be parsed.`
+    : `GSD ${scope} preferences ${level}: ${diagnostic.path} contains invalid settings.`;
+  const detail = formatPreferenceDiagnosticDetail(diagnostic);
+  const impact = diagnostic.ignored
+    ? "Preferences from this file were ignored; auto-mode may be using defaults."
+    : "Invalid settings were ignored or sanitized; auto-mode may be using defaults for them.";
+  return `${heading}\n${detail}\n${impact}\nRun /gsd doctor for details.`;
+}
+
+export function formatPreferenceDiagnosticDetail(diagnostic: PreferenceDiagnostic): string {
+  if (diagnostic.line !== undefined && diagnostic.column !== undefined) {
+    return `YAML error at line ${diagnostic.line}, column ${diagnostic.column}: ${diagnostic.message}`;
+  }
+  return diagnostic.message;
+}
+
+export function notifyPreferenceDiagnostics(
+  ctx: PreferenceNotificationContext,
+  basePath?: string,
+  options?: PreferenceDiagnosticNotificationOptions,
+): number {
+  let notified = 0;
+  for (const diagnostic of collectPreferenceDiagnostics(basePath)) {
+    const signature = preferenceDiagnosticNotificationSignature(diagnostic, options?.surface);
+    if (notifiedPreferenceDiagnostics.has(signature)) continue;
+    notifiedPreferenceDiagnostics.add(signature);
+    ctx.ui.notify(
+      formatPreferenceDiagnostic(diagnostic),
+      diagnostic.severity === "error" ? "error" : "warning",
+    );
+    notified++;
+  }
+  return notified;
+}
+
+export function _resetPreferenceDiagnosticNotificationsForTests(): void {
+  notifiedPreferenceDiagnostics.clear();
+}
+
+function preferenceDiagnosticSignature(diagnostic: PreferenceDiagnostic): string {
+  return [
+    diagnostic.path,
+    diagnostic.scope,
+    diagnostic.severity,
+    diagnostic.kind,
+    diagnostic.message,
+    diagnostic.line ?? "",
+    diagnostic.column ?? "",
+    diagnostic.ignored === true ? "ignored" : "",
+    diagnostic.sanitized === true ? "sanitized" : "",
+  ].join("\u0000");
+}
+
+function preferenceDiagnosticNotificationSignature(
+  diagnostic: PreferenceDiagnostic,
+  surface = "default",
+): string {
+  return `${surface}\u0000${preferenceDiagnosticSignature(diagnostic)}`;
+}

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

@@ -25,7 +25,8 @@ import type {
   ResolvedModelConfig,
   AutoSupervisorConfig,
 } from "./preferences-types.js";
-import { loadEffectiveGSDPreferences, getGlobalGSDPreferencesPath } from "./preferences.js";
+import { clearGSDPreferencesCache, loadEffectiveGSDPreferences, getGlobalGSDPreferencesPath } from "./preferences.js";
+import { getUnitPhaseChain } from "./unit-registry.js";
 
 // Re-export types so existing consumers of ./preferences-models.js keep working
 export type { GSDPhaseModelConfig, GSDModelConfig, GSDModelConfigV2, ResolvedModelConfig } from "./preferences-types.js";
@@ -49,53 +50,16 @@ export function resolveModelForUnit(unitType: string): string | undefined {
  * (`resolveThinkingLevelForUnit`) so the two never drift (ADR-026).
  */
 export function phaseChainForUnit(unitType: string): GSDModelPhaseKey[] | undefined {
-  switch (unitType) {
-    case "research-milestone":
-    case "research-slice":
-    // Deep-mode project research orchestrator. Reads PROJECT.md / REQUIREMENTS.md
-    // and fans out research subagents. Routes to the research bucket.
-    case "research-project":
-      return ["research"];
-    case "plan-milestone":
-    case "plan-slice":
-    case "refine-slice":
-    case "replan-slice":
-      return ["planning"];
-    // Deep-mode project-level discussion units route to the same model bucket
-    // as milestone-level discussion (interactive interview style). Workflow
-    // preferences and research-decision are tiny ask_user_questions style units
-    // that share the discuss bucket because they are conversational. All fall
-    // back to planning when no `discuss` bucket is set.
-    case "discuss-milestone":
-    case "discuss-slice":
-    case "discuss-project":
-    case "discuss-requirements":
-    case "workflow-preferences":
-    case "research-decision":
-      return ["discuss", "planning"];
-    case "execute-task":
-    case "reactive-execute":
-      return ["execution"];
-    case "execute-task-simple":
-      return ["execution_simple", "execution"];
-    case "complete-slice":
-    case "complete-milestone":
-    case "worktree-merge":
-      return ["completion"];
-    case "run-uat":
-      return ["uat", "completion"];
-    case "reassess-roadmap":
-    case "rewrite-docs":
-    case "gate-evaluate":
-    case "validate-milestone":
-      return ["validation", "planning"];
-    default:
-      // Subagent unit types (e.g., "subagent", "subagent/scout")
-      if (unitType === "subagent" || unitType.startsWith("subagent/")) {
-        return ["subagent"];
-      }
-      return undefined;
+  // Unit types declare their chain on their Unit Descriptor (ADR-033).
+  const declared = getUnitPhaseChain(unitType);
+  if (declared) return [...declared];
+  // Dispatch types without a Unit Descriptor.
+  if (unitType === "worktree-merge") return ["completion"];
+  // Subagent unit types (e.g., "subagent", "subagent/scout")
+  if (unitType === "subagent" || unitType.startsWith("subagent/")) {
+    return ["subagent"];
   }
+  return undefined;
 }
 
 /**
@@ -130,8 +94,16 @@ function resolveWinningPhase(
  * - Legacy: `planning: claude-opus-4-6`
  * - Extended: `planning: { model: claude-opus-4-6, fallbacks: [glm-5, minimax-m2.5] }`
  */
-export function resolveModelWithFallbacksForUnit(unitType: string): ResolvedModelConfig | undefined {
-  const prefs = loadEffectiveGSDPreferences(undefined, { availableModelIds: [] });
+export function resolveModelWithFallbacksForUnit(
+  unitType: string,
+  basePath?: string,
+  availableModelIds?: string[],
+  preferredModelId?: string,
+): ResolvedModelConfig | undefined {
+  const loadOpts = availableModelIds !== undefined || preferredModelId !== undefined
+    ? { availableModelIds, preferredModelId }
+    : undefined;
+  const prefs = loadEffectiveGSDPreferences(basePath, loadOpts);
   const chain = phaseChainForUnit(unitType);
   if (!chain) return undefined;
   const winner = resolveWinningPhase(prefs?.preferences?.models as GSDModelConfigV2 | undefined, chain);
@@ -177,8 +149,13 @@ export function resolveModelWithFallbacksForUnit(unitType: string): ResolvedMode
  * floor. Session level, defaults, the floor, and capability clamping are NOT
  * applied here.
  */
-export function resolveThinkingLevelForUnit(unitType: string): GSDThinkingLevel | undefined {
-  const prefs = loadEffectiveGSDPreferences(undefined, { availableModelIds: [] })?.preferences;
+export function resolveThinkingLevelForUnit(
+  unitType: string,
+  basePath?: string,
+  availableModelIds?: string[],
+): GSDThinkingLevel | undefined {
+  const loadOpts = availableModelIds !== undefined ? { availableModelIds } : undefined;
+  const prefs = loadEffectiveGSDPreferences(basePath, loadOpts)?.preferences;
   if (!prefs) return undefined;
   const chain = phaseChainForUnit(unitType);
   if (!chain) return undefined;
@@ -214,15 +191,26 @@ export function resolveThinkingLevelForUnit(unitType: string): GSDThinkingLevel
  * `openai-codex/gpt-5.4`).  When a bare ID is found and sessionProvider
  * is available, the session provider is used.  Without sessionProvider,
  * bare IDs are still returned with provider set to the bare ID itself
- * so downstream resolution (resolveModelId) can match it.
+ * so downstream resolution (resolveModelId) can match it. Accepts an optional
+ * `sessionModelId` so token-profile defaults can preserve the selected model
+ * before auto-mode captures its start snapshot.
  *
  * Returns `{ provider, id }` or `undefined` if no model preference is
  * configured.
  */
 export function resolveDefaultSessionModel(
   sessionProvider?: string,
+  basePath?: string,
+  availableModelIds?: string[],
+  sessionModelId?: string,
 ): { provider: string; id: string } | undefined {
-  const prefs = loadEffectiveGSDPreferences(undefined, { availableModelIds: [] });
+  const preferredModelId = sessionModelId && sessionProvider
+    ? `${sessionProvider}/${sessionModelId}`
+    : sessionModelId;
+  const loadOpts = availableModelIds !== undefined || preferredModelId !== undefined
+    ? { availableModelIds, preferredModelId }
+    : undefined;
+  const prefs = loadEffectiveGSDPreferences(basePath, loadOpts);
   const models = prefs?.preferences?.models;
   if (!models) return undefined;
 
@@ -417,6 +405,7 @@ export function updatePreferencesModels(models: GSDModelConfigV2): void {
   }
 
   writeFileSync(prefsPath, content, "utf-8");
+  clearGSDPreferencesCache();
 }
 
 /**
@@ -448,7 +437,10 @@ export function resolveAutoSupervisorConfig(): AutoSupervisorConfig {
 
 // ─── Token Profile Resolution ─────────────────────────────────────────────
 
-const VALID_TOKEN_PROFILES = new Set<TokenProfile>(["budget", "balanced", "quality", "burn-max"]);
+export const VALID_TOKEN_PROFILES = new Set<TokenProfile>(["budget", "balanced", "quality", "burn-max"]);
+
+/** D046: balanced is the implicit profile when `token_profile` is omitted. */
+export const DEFAULT_TOKEN_PROFILE: TokenProfile = "balanced";
 
 /**
  * Per-phase tier intentions for each token profile.
@@ -494,27 +486,34 @@ const PROFILE_TIER_MAP: Record<TokenProfile, Record<string, ComplexityTier>> = {
  *
  * Model IDs are resolved from capability tiers, not hardcoded to any
  * provider. When available models are known (runtime), the resolver picks
- * the best match across all configured providers. When not known (e.g.,
- * early startup), falls back to canonical Anthropic model IDs.
+ * the best match on the anchor provider (session / auto-start model). Callers
+ * scope the available-model list via `modelIdsForProfileResolution` so token
+ * profiles do not hop to a cheaper provider (e.g. Gemini Flash) when the user
+ * is working on OpenAI or Anthropic. When the selected/session model is known,
+ * it is preferred for tiers it can satisfy. When the registry is unavailable
+ * (e.g., early startup), falls back to canonical Anthropic model IDs.
  *
  * @param profile           The token profile to resolve
  * @param availableModelIds Optional list of available model IDs for cross-provider resolution.
  *                          Undefined means the registry is unavailable.
  * @param routingConfig     Optional routing config for tier model pins.
+ * @param preferredModelId  Optional selected/session model ID to prefer.
  */
 export function resolveProfileDefaults(
   profile: TokenProfile,
   availableModelIds?: string[],
   routingConfig: DynamicRoutingConfig = defaultRoutingConfig(),
+  preferredModelId?: string,
 ): Partial<GSDPreferences> {
   // burn-max never writes model defaults — preserve user-selected models.
   // For the other three profiles, derive concrete model IDs from the tier map
   // against the available-model list when the registry is provided. If callers
   // omit the registry entirely, use canonical fallbacks explicitly.
   const tierMap = PROFILE_TIER_MAP[profile];
-  const resolveTierModel = (tier: ComplexityTier): string => Array.isArray(availableModelIds)
-    ? resolveModelForTier(tier, availableModelIds, routingConfig)
-    : canonicalModelForTier(tier);
+  const resolveTierModel = (tier: ComplexityTier): string =>
+    Array.isArray(availableModelIds) || preferredModelId
+      ? resolveModelForTier(tier, availableModelIds ?? [], routingConfig, undefined, preferredModelId)
+      : canonicalModelForTier(tier);
   const models: GSDModelConfigV2 | undefined = profile === "burn-max"
     ? undefined
     : {

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

@@ -594,8 +594,24 @@ export interface LoadedGSDPreferences {
   path: string;
   scope: "global" | "project";
   preferences: GSDPreferences;
+  /** True when the file exists but its contents were ignored before merging. */
+  ignored?: boolean;
   /** Validation warnings (unknown keys, type mismatches, deprecations). Empty when preferences are clean. */
   warnings?: string[];
+  /** Structured parse/validation diagnostics for user-visible reporting. */
+  diagnostics?: PreferenceDiagnostic[];
+}
+
+export interface PreferenceDiagnostic {
+  path: string;
+  scope: "global" | "project";
+  severity: "error" | "warning";
+  kind: "parse" | "validation";
+  message: string;
+  line?: number;
+  column?: number;
+  ignored?: boolean;
+  sanitized?: boolean;
 }
 
 export interface SkillResolution {