@opengsd/gsd-pi 1.1.1-dev.9f86580 → 1.1.1-dev.b2556262

package/dist/resources/extensions/gsd/auto-model-selection.js

@@ -3,7 +3,8 @@
  * Handles complexity-based routing, model resolution across providers,
  * and fallback chains.
  */
-import { resolveModelWithFallbacksForUnit, resolveDynamicRoutingConfig } from "./preferences.js";
+import { clampThinkingLevel } from "@gsd/pi-ai";
+import { resolveModelWithFallbacksForUnit, resolveThinkingLevelForUnit, resolveDynamicRoutingConfig } from "./preferences.js";
 import { classifyUnitComplexity, extractTaskMetadata, tierLabel } from "./complexity-classifier.js";
 import { resolveModelForComplexity, escalateTier, getEligibleModels, loadCapabilityOverrides, adjustToolSet } from "./model-router.js";
 import { getLedger, getProjectTotals } from "./metrics.js";
@@ -228,10 +229,88 @@ function restoreToolBaseline(pi) {
         pi.setActiveTools([...baseline]);
     }
 }
-function reapplyThinkingLevel(pi, level) {
+/**
+ * Apply the desired reasoning effort for the just-selected model, clamping to
+ * what the model actually supports (ADR-026). An unsupported level is never
+ * sent to the provider — it is clamped via `clampThinkingLevel` and the
+ * mismatch is surfaced once per (model, requested-level). Returns the level
+ * actually applied so callers can record it.
+ */
+export function applyThinkingLevelForModel(pi, desired, model, ctx) {
+    if (!desired)
+        return desired;
+    // Capability-clamp only when we have a bare string level AND the model
+    // advertises reasoning capability (`reasoning` is always present on real
+    // registry models). Richer host snapshot shapes (e.g. `{ effort: "high" }`)
+    // and partial model objects are applied verbatim — we never coerce an unknown
+    // shape into a string or guess capability we can't see.
+    if (typeof desired === "string" && model != null && typeof model === "object" && "reasoning" in model) {
+        const clamped = clampThinkingLevel(model, desired);
+        pi.setThinkingLevel(clamped);
+        if (clamped !== desired) {
+            const key = `${model.provider}/${model.id}:${desired}`;
+            if (!_warnedThinkingClamp.has(key)) {
+                _warnedThinkingClamp.add(key);
+                ctx.ui.notify(`Thinking level '${desired}' not supported by ${model.provider}/${model.id}; using '${clamped}'.`, "warning");
+            }
+        }
+        return clamped;
+    }
+    pi.setThinkingLevel(desired);
+    return desired;
+}
+/** Warn-once guard for capability clamps, keyed by `provider/id:requested`. */
+const _warnedThinkingClamp = new Set();
+/** Warn-once guard for the execute-task floor punch-through advisory. */
+let _warnedExecuteTaskFloorBypass = false;
+/**
+ * Ascending severity order for reasoning levels (matches @gsd/pi-agent-core
+ * `ThinkingLevel`). Used only for floor comparisons below.
+ */
+const THINKING_LEVEL_ORDER = [
+    "off",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+];
+/**
+ * Minimum reasoning level for code-writing units.
+ *
+ * `execute-task` is the only unit that edits source. With a low/minimal
+ * thinking level a model does not plan its edits and compensates by re-reading
+ * the same files dozens of times per task (measured: index.html read ~49× in a
+ * single task on a minimal-thinking model) and shelling out to `nl`/`sed` to
+ * re-locate code after every edit invalidates its line numbers. Flooring the
+ * level for this unit type removes that read/bash thrash. Planning, research,
+ * and lifecycle units are unaffected.
+ */
+const EXECUTE_TASK_MIN_THINKING_LEVEL = "medium";
+function thinkingLevelRank(level) {
+    const idx = THINKING_LEVEL_ORDER.indexOf(level);
+    return idx === -1 ? 0 : idx;
+}
+/**
+ * Raise (never lower) the thinking level for code-writing units to a sane
+ * floor. Returns the input unchanged for non-`execute-task` units, when no
+ * level was captured, or when the captured level already meets the floor.
+ */
+export function floorThinkingLevelForUnit(unitType, level) {
+    if (unitType !== "execute-task")
+        return level;
     if (!level)
-        return;
-    pi.setThinkingLevel(level);
+        return level;
+    // Only act on the recognized string levels. Any other shape (e.g. a richer
+    // host snapshot object) is passed through untouched so we never coerce an
+    // unknown representation into a bare string the host can't apply.
+    if (!THINKING_LEVEL_ORDER.includes(level)) {
+        return level;
+    }
+    if (thinkingLevelRank(level) >= thinkingLevelRank(EXECUTE_TASK_MIN_THINKING_LEVEL)) {
+        return level;
+    }
+    return EXECUTE_TASK_MIN_THINKING_LEVEL;
 }
 export function resolvePreferredModelConfig(unitType, autoModeStartModel, isAutoMode = true) {
     const explicitConfig = resolveModelWithFallbacksForUnit(unitType);
@@ -282,6 +361,32 @@ sessionModelOverride,
 /** Thinking level captured at auto-mode start and re-applied after model swaps. */
 autoModeStartThinkingLevel) {
     const uokFlags = resolveUokFlags(prefs);
+    // Resolve reasoning effort for this dispatch (ADR-026). An explicit per-phase
+    // thinking config (inline `models.<phase>.thinking` or the separate `thinking`
+    // block) expresses hard user intent: it bypasses the execute-task floor and is
+    // honored verbatim, then capability-clamped per model at apply time below.
+    // With no explicit level, fall back to the auto-start session level and raise
+    // the code-writing floor — preserving prior behavior exactly. Recomputed per
+    // dispatch so neither the floor nor a phase override leaks to other units.
+    const explicitThinkingLevel = resolveThinkingLevelForUnit(unitType);
+    const desiredThinkingLevel = explicitThinkingLevel
+        ?? floorThinkingLevelForUnit(unitType, autoModeStartThinkingLevel);
+    if (explicitThinkingLevel) {
+        if (unitType === "execute-task" &&
+            thinkingLevelRank(explicitThinkingLevel) < thinkingLevelRank(EXECUTE_TASK_MIN_THINKING_LEVEL) &&
+            !_warnedExecuteTaskFloorBypass) {
+            _warnedExecuteTaskFloorBypass = true;
+            ctx.ui.notify(`Explicit execution thinking '${explicitThinkingLevel}' is below the measured execute-task floor ` +
+                `(${EXECUTE_TASK_MIN_THINKING_LEVEL}); honoring it as configured. Low reasoning on code edits can ` +
+                `cause repeated file re-reads.`, "warning");
+        }
+    }
+    else if (verbose &&
+        desiredThinkingLevel &&
+        desiredThinkingLevel !== autoModeStartThinkingLevel) {
+        ctx.ui.notify(`Thinking level raised to ${desiredThinkingLevel} for ${unitType} (was ${autoModeStartThinkingLevel ?? "unset"})`, "info");
+    }
+    let appliedThinkingLevel = null;
     const effectiveSessionModelOverride = sessionModelOverride === undefined
         ? getSessionModelOverride(ctx.sessionManager.getSessionId())
         : (sessionModelOverride ?? undefined);
@@ -559,7 +664,7 @@ autoModeStartThinkingLevel) {
             const ok = await pi.setModel(model, { persist: false });
             if (ok) {
                 appliedModel = model;
-                reapplyThinkingLevel(pi, autoModeStartThinkingLevel);
+                appliedThinkingLevel = applyThinkingLevelForModel(pi, desiredThinkingLevel, model, ctx);
                 // ADR-005: Adjust active tool set for the selected model's provider capabilities.
                 // Hard-filter incompatible tools, then let extensions override via adjust_tool_set hook.
                 const activeToolNames = pi.getActiveTools();
@@ -617,7 +722,7 @@ autoModeStartThinkingLevel) {
                 if (!ok)
                     continue;
                 appliedModel = model;
-                reapplyThinkingLevel(pi, autoModeStartThinkingLevel);
+                appliedThinkingLevel = applyThinkingLevelForModel(pi, desiredThinkingLevel, model, ctx);
                 attemptedPolicyEligible = true;
                 if (verbose) {
                     ctx.ui.notify(`Model policy: configured model unavailable; using ${model.provider}/${model.id}`, "info");
@@ -647,18 +752,32 @@ autoModeStartThinkingLevel) {
                         const fallbackOk = await pi.setModel(byId, { persist: false });
                         if (fallbackOk) {
                             appliedModel = byId;
-                            reapplyThinkingLevel(pi, autoModeStartThinkingLevel);
+                            appliedThinkingLevel = applyThinkingLevelForModel(pi, desiredThinkingLevel, byId, ctx);
                         }
                     }
                 }
                 else {
                     appliedModel = startModel;
-                    reapplyThinkingLevel(pi, autoModeStartThinkingLevel);
+                    appliedThinkingLevel = applyThinkingLevelForModel(pi, desiredThinkingLevel, startModel, ctx);
                 }
             }
         }
     }
-    return { routing, appliedModel };
+    // If no model branch applied a thinking level (e.g. interactive guided-flow
+    // with a `thinking:` block but no per-phase model and no start model), still
+    // honor an explicitly configured phase thinking level against the current
+    // session model. Only the explicit path runs here — the floored session
+    // default is intentionally left untouched so no-config interactive runs keep
+    // the user's /model thinking level. (ADR-026)
+    if (appliedThinkingLevel == null && explicitThinkingLevel && ctx.model) {
+        // Prefer the full registry model (carries reasoning capability so the level
+        // can be clamped); fall back to ctx.model. Always route through
+        // applyThinkingLevelForModel so the clamp runs whenever capability metadata
+        // exists — never a raw verbatim setThinkingLevel that bypasses it (ADR-026).
+        const current = resolveModelId(`${ctx.model.provider}/${ctx.model.id}`, ctx.modelRegistry?.getAvailable?.() ?? [], ctx.model.provider) ?? ctx.model;
+        appliedThinkingLevel = applyThinkingLevelForModel(pi, explicitThinkingLevel, current, ctx);
+    }
+    return { routing, appliedModel, appliedThinkingLevel };
 }
 /**
  * Resolve a model ID string to a model object from the available models list.

package/dist/resources/extensions/gsd/auto-post-unit.js

@@ -1280,6 +1280,7 @@ export async function postUnitPreVerification(pctx, opts) {
                 logError("engine", "triage resolution failed", { error: err.message });
             }
         }
+        let blockingContentViolation = null;
         // ── Safety harness: post-unit validation ──
         try {
             const { loadEffectiveGSDPreferences } = await import("./preferences.js");
@@ -1399,8 +1400,15 @@ export async function postUnitPreVerification(pctx, opts) {
                         const artifactPath = resolveArtifactForContent(s.currentUnit.type, s.currentUnit.id, s.basePath);
                         const contentViolations = validateContent(s.currentUnit.type, artifactPath);
                         for (const v of contentViolations) {
-                            logWarning("safety", `content: ${v.reason}`);
-                            ctx.ui.notify(`Content validation: ${v.reason}`, "warning");
+                            if (v.severity === "error") {
+                                blockingContentViolation ??= v.reason;
+                                logError("safety", `content: ${v.reason}`);
+                                ctx.ui.notify(`Content validation: ${v.reason}`, "error");
+                            }
+                            else {
+                                logWarning("safety", `content: ${v.reason}`);
+                                ctx.ui.notify(`Content validation: ${v.reason}`, "warning");
+                            }
                         }
                     }
                     catch (e) {
@@ -1573,6 +1581,15 @@ export async function postUnitPreVerification(pctx, opts) {
                     return "continue";
                 }
             }
+            if (blockingContentViolation && triggerArtifactVerified) {
+                triggerArtifactVerified = false;
+                debugLog("postUnit", {
+                    phase: "content-validation-blocked-artifact",
+                    unitType: s.currentUnit.type,
+                    unitId: s.currentUnit.id,
+                    reason: blockingContentViolation,
+                });
+            }
             // When artifact verification fails for a unit type that has a known expected
             // artifact, ask the caller to retry so it re-dispatches with failure context
             // instead of blindly re-dispatching the same unit (#1571).

package/dist/resources/extensions/gsd/auto-prompts.js

@@ -8,7 +8,7 @@
  * utility.
  */
 import { loadFile, parseContinue, parseSummary, loadActiveOverrides, formatOverridesSection } from "./files.js";
-import { hasVerdict, getUatType, extractVerdict } from "./verdict-parser.js";
+import { hasVerdict, extractVerdict } from "./verdict-parser.js";
 import { loadPrompt, inlineTemplate } from "./prompt-loader.js";
 import { resolveMilestoneFile, resolveSliceFile, resolveSlicePath, resolveTasksDir, resolveTaskFiles, resolveTaskFile, relMilestoneFile, relSliceFile, relSlicePath, relMilestonePath, resolveGsdRootFile, relGsdRootFile, resolveRuntimeFile, } from "./paths.js";
 import { resolveInlineLevel, loadEffectiveGSDPreferences } from "./preferences.js";
@@ -27,11 +27,11 @@ import { logWarning } from "./workflow-logger.js";
 import { inlineGraphSubgraph } from "./graph-context.js";
 import { buildExtractionStepsBlock } from "./commands-extract-learnings.js";
 import { classifyProject } from "./detection.js";
-import { hasBrowserRequiredText } from "./browser-evidence.js";
 import { debugLog } from "./debug-logger.js";
 import { buildSkillActivationBlock, buildSkillDiscoveryVars } from "./skill-activation.js";
 import { findMilestoneIds } from "./milestone-ids.js";
 import { buildRunUatPresentationForType, RUN_UAT_TOOL_PRESENTATION_PLAN_ID } from "./tool-presentation-plan.js";
+import { resolveEffectiveUatType, shouldDispatchUatForContent } from "./uat-policy.js";
 export { buildSkillActivationBlock, buildSkillDiscoveryVars };
 // ─── Preamble Cap ─────────────────────────────────────────────────────────────
 /**
@@ -228,17 +228,6 @@ function prependContextModeToBlock(unitType, base, block, renderMode = "standalo
         return contextMode;
     return `${contextMode}\n\n${block}`;
 }
-function resolveEffectiveUatType(content) {
-    const uatType = getUatType(content);
-    if (uatType === "artifact-driven" && hasBrowserRequiredText(content)) {
-        return "browser-executable";
-    }
-    return uatType;
-}
-function shouldDispatchUatForContent(content, prefs) {
-    const uatType = resolveEffectiveUatType(content);
-    return !!prefs?.uat_dispatch || uatType !== "artifact-driven" || hasBrowserRequiredText(content);
-}
 // ─── Executor Constraints ─────────────────────────────────────────────────────
 /**
  * Format executor context constraints for injection into the plan-slice prompt.
@@ -3077,7 +3066,23 @@ export async function buildReassessRoadmapPrompt(mid, midTitle, completedSliceId
     });
 }
 // ─── Reactive Execute Prompt ──────────────────────────────────────────────
-export async function buildReactiveExecutePrompt(mid, midTitle, sid, sTitle, readyTaskIds, base, subagentModel, opts) {
+/**
+ * Build the `with model: "…" and thinking: "…"` suffix injected into a prompt
+ * that instructs the coordinator how to dispatch a `subagent` call. Either or
+ * both may be absent (ADR-026 / #508).
+ */
+function subagentCallSuffix(model, thinking) {
+    const parts = [];
+    if (model)
+        parts.push(`model: "${model}"`);
+    if (thinking)
+        parts.push(`thinking: "${thinking}"`);
+    return parts.length > 0 ? ` with ${parts.join(" and ")}` : "";
+}
+export async function buildReactiveExecutePrompt(mid, midTitle, sid, sTitle, readyTaskIds, base, subagentModel, 
+// Reasoning effort travels inside opts here (not as a positional param) so
+// existing positional `opts` callers don't shift (#508).
+opts) {
     const { loadSliceTaskIO, deriveTaskGraph, graphMetrics } = await import("./reactive-graph.js");
     // Build graph for context
     const taskIO = await loadSliceTaskIO(base, mid, sid);
@@ -3151,7 +3156,7 @@ export async function buildReactiveExecutePrompt(mid, midTitle, sid, sTitle, rea
             "",
             `When done, say: "Task ${tid} complete."`,
         ].join("\n");
-        const modelSuffix = subagentModel ? ` with model: "${subagentModel}"` : "";
+        const modelSuffix = subagentCallSuffix(subagentModel, opts?.subagentThinking);
         subagentSections.push([
             `### ${tid}: ${tTitle}`,
             "",
@@ -3217,10 +3222,10 @@ function renderGatesToCloseBlock(gates, opts) {
     }
     return lines.join("\n").trimEnd();
 }
-export async function buildParallelResearchSlicesPrompt(mid, midTitle, slices, basePath, subagentModel) {
+export async function buildParallelResearchSlicesPrompt(mid, midTitle, slices, basePath, subagentModel, subagentThinking) {
     // Build individual research-slice prompts for each slice
     const subagentSections = [];
-    const modelSuffix = subagentModel ? ` with model: "${subagentModel}"` : "";
+    const modelSuffix = subagentCallSuffix(subagentModel, subagentThinking);
     for (const slice of slices) {
         const slicePrompt = await buildResearchSlicePrompt(mid, midTitle, slice.id, slice.title, basePath, { contextModeRenderMode: "nested" });
         subagentSections.push([
@@ -3242,7 +3247,7 @@ export async function buildParallelResearchSlicesPrompt(mid, midTitle, slices, b
         subagentPrompts: subagentSections.join("\n\n---\n\n"),
     });
 }
-export async function buildGateEvaluatePrompt(mid, midTitle, sid, sTitle, base, subagentModel) {
+export async function buildGateEvaluatePrompt(mid, midTitle, sid, sTitle, base, subagentModel, subagentThinking) {
     // Pull only the gates this turn actually owns (Q3/Q4). Filter via the
     // registry so that scope:"slice" gates owned by other turns (Q8) can't
     // leak into this prompt and can't block dispatch via silent skip.
@@ -3291,7 +3296,7 @@ export async function buildGateEvaluatePrompt(mid, midTitle, sid, sTitle, base,
             "- `rationale`: one-sentence justification",
             "- `findings`: detailed markdown findings (or empty if omitted)",
         ].join("\n");
-        const modelSuffix = subagentModel ? ` with model: "${subagentModel}"` : "";
+        const modelSuffix = subagentCallSuffix(subagentModel, subagentThinking);
         subagentSections.push([
             `### ${def.id}: ${def.question}`,
             "",

package/dist/resources/extensions/gsd/auto-recovery.js

@@ -14,7 +14,7 @@ import { appendEvent } from "./workflow-events.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import { clearParseCache } from "./files.js";
 import { parseRoadmap as parseLegacyRoadmap, parsePlan as parseLegacyPlan } from "./parsers-legacy.js";
-import { isDbAvailable, getTask, getSlice, getSliceTasks, getPendingGates, updateTaskStatus, updateSliceStatus, insertSlice, getMilestone, getMilestoneSlices, getLatestAssessmentByScope, updateMilestoneStatus, refreshOpenDatabaseFromDisk, transaction } from "./gsd-db.js";
+import { isDbAvailable, getTask, getSlice, getSliceTasks, getPendingGatesForTurn, updateTaskStatus, updateSliceStatus, insertSlice, getMilestone, getMilestoneSlices, getLatestAssessmentByScope, updateMilestoneStatus, refreshOpenDatabaseFromDisk, transaction, } from "./gsd-db.js";
 import { isValidationTerminal } from "./state.js";
 import { getErrorMessage } from "./error-utils.js";
 import { logWarning, logError } from "./workflow-logger.js";
@@ -329,7 +329,9 @@ export function verifyExpectedArtifact(unitType, unitId, base) {
         if (gateIds.length === 0)
             return true;
         try {
-            const pending = getPendingGates(mid, sid, "slice");
+            if (!isDbAvailable())
+                return false;
+            const pending = getPendingGatesForTurn(mid, sid, "gate-evaluate");
             const pendingIds = new Set(pending.map((g) => g.gate_id));
             // All dispatched gates must no longer be pending
             for (const gid of gateIds) {

package/dist/resources/extensions/gsd/auto-runtime-state.js

@@ -41,3 +41,6 @@ export function clearToolInvocationError() {
         return;
     autoSession.lastToolInvocationError = null;
 }
+export function getSourceObservationStore() {
+    return autoSession.sourceObservations;
+}

package/dist/resources/extensions/gsd/auto-start.js

@@ -1208,7 +1208,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         s.autoStartTime = Date.now();
         s.resourceVersionOnStart = readResourceVersion();
         s.pendingQuickTasks = [];
-        s.currentUnit = null;
+        s.clearCurrentUnit();
         s.currentMilestoneId ??=
             strandedRecoveryAction?.milestoneId ??
                 (deepProjectStagePending ? null : state.activeMilestone?.id ?? null);

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

@@ -822,7 +822,7 @@ export async function cleanupAfterLoopExit(ctx) {
     const preserveStepSurface = s.preserveStepSurfaceAfterLoopExit;
     const preserveCompletionSurface = s.completionStopInProgress;
     const preservePausedSurface = s.paused;
-    s.currentUnit = null;
+    s.clearCurrentUnit();
     s.active = false;
     deactivateGSD();
     clearUnitTimeout();
@@ -847,12 +847,15 @@ export async function cleanupAfterLoopExit(ctx) {
     // A transient provider-error pause intentionally leaves the paused badge
     // visible so the user still has a resumable auto-mode signal on screen.
     if (!s.paused) {
-        if (preserveStepSurface) {
-            s.preserveStepSurfaceAfterLoopExit = false;
-        }
-        else if (preserveCompletionSurface) {
+        if (preserveCompletionSurface) {
             ctx.ui.setStatus("gsd-auto", undefined);
             s.completionStopInProgress = false;
+            if (preserveStepSurface) {
+                s.preserveStepSurfaceAfterLoopExit = false;
+            }
+        }
+        else if (preserveStepSurface) {
+            s.preserveStepSurfaceAfterLoopExit = false;
         }
         else {
             ctx.ui.setStatus("gsd-auto", undefined);
@@ -1492,7 +1495,7 @@ export async function pauseAuto(ctx, _pi, _errorContext, options = {}) {
             // Non-fatal — best-effort closeout on pause
             logWarning("engine", `unit closeout on pause failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
         }
-        s.currentUnit = null;
+        s.clearCurrentUnit();
     }
     // Keep STATE.md aligned with the DB-backed state before releasing pause state.
     // Without this, an interrupted deep run can leave STATE.md saying "no active
@@ -2627,7 +2630,7 @@ export async function dispatchHookUnit(ctx, pi, hookName, triggerUnitType, trigg
         s.stepMode = true;
         s.cmdCtx = ctx;
         s.autoStartTime = Date.now();
-        s.currentUnit = null;
+        s.clearCurrentUnit();
         s.pendingQuickTasks = [];
     }
     // ADR-016 phase 2 / B2 (#5620): hook-trigger basePath transition. Treats
@@ -2641,23 +2644,23 @@ export async function dispatchHookUnit(ctx, pi, hookName, triggerUnitType, trigg
     }
     const hookUnitType = `hook/${hookName}`;
     const hookStartedAt = Date.now();
-    s.currentUnit = {
+    s.setCurrentUnit({
         type: triggerUnitType,
         id: triggerUnitId,
         startedAt: hookStartedAt,
         workspaceRoot: s.basePath,
-    };
+    });
     const result = await s.cmdCtx.newSession({ workspaceRoot: s.basePath });
     if (result.cancelled) {
         await stopAuto(ctx, pi);
         return false;
     }
-    s.currentUnit = {
+    s.setCurrentUnit({
         type: hookUnitType,
         id: triggerUnitId,
         startedAt: hookStartedAt,
         workspaceRoot: s.basePath,
-    };
+    });
     if (hookModel) {
         const availableModels = ctx.modelRegistry.getAvailable();
         const match = resolveModelId(hookModel, availableModels, ctx.model?.provider);

package/dist/resources/extensions/gsd/bootstrap/db-tools.js

@@ -664,7 +664,7 @@ export function registerDbTools(pi) {
                 files: Type.Array(Type.String(), { description: "Array<string> of files likely touched; pass [\"path\"] or [], never a single string" }),
                 verify: Type.String({ description: "Verification command or block" }),
                 inputs: Type.Array(Type.String(), { description: "Array<string> of input files or references; pass [\"path\"] or [], never a single string" }),
-                expectedOutput: Type.Array(Type.String(), { description: "Array<string> of expected output files or artifacts; pass [\"path\"] or [], never a single string" }),
+                expectedOutput: Type.Array(Type.String(), { description: "Array<string> of files this task creates or overwrites; pass [\"path\"] or [], never prose or a single string" }),
                 observabilityImpact: Type.Optional(Type.String({ description: "Task observability impact" })),
             }), { description: "Planned tasks for the slice" }),
             // ── Enrichment metadata (optional — defaults to empty) ────────────
@@ -740,7 +740,7 @@ export function registerDbTools(pi) {
             files: Type.Array(Type.String(), { description: "Array<string> of files likely touched; pass [\"path\"] or [], never a single string" }),
             verify: Type.String({ description: "Verification command or block" }),
             inputs: Type.Array(Type.String(), { description: "Array<string> of input files or references; pass [\"path\"] or [], never a single string" }),
-            expectedOutput: Type.Array(Type.String(), { description: "Array<string> of expected output files or artifacts; pass [\"path\"] or [], never a single string" }),
+            expectedOutput: Type.Array(Type.String(), { description: "Array<string> of files this task creates or overwrites; pass [\"path\"] or [], never prose or a single string" }),
             observabilityImpact: Type.Optional(Type.String({ description: "Task observability impact" })),
             // Single-writer v3 audit trail (Stream 2): caller-provided actor identity + causation.
             actorName: Type.Optional(Type.String({ description: "Caller-provided actor identity for the audit trail (e.g. 'executor-01', 'gsd-orchestrator')" })),
@@ -1069,7 +1069,7 @@ export function registerDbTools(pi) {
                 files: Type.Array(Type.String(), { description: "Files likely touched" }),
                 verify: Type.String({ description: "Verification command or block" }),
                 inputs: Type.Array(Type.String(), { description: "Input files or references" }),
-                expectedOutput: Type.Array(Type.String(), { description: "Expected output files or artifacts" }),
+                expectedOutput: Type.Array(Type.String(), { description: "Files this task creates or overwrites" }),
             }), { description: "Tasks to upsert (update existing or insert new)" }),
             removedTaskIds: Type.Array(Type.String(), { description: "Task IDs to remove from the slice" }),
             // Single-writer v3 audit trail (Stream 2): caller-provided actor identity + causation.