@opengsd/gsd-pi 1.5.0 → 1.6.0-dev.aa7f94e8

package/dist/resources/extensions/gsd/preferences-models.js

@@ -66,6 +66,39 @@ function resolveWinningPhase(models, chain) {
     }
     return undefined;
 }
+/**
+ * Normalize a single model field into a {@link ResolvedModelConfig}.
+ *
+ * Accepts either the legacy bare-string form or the extended object form
+ * (`{ model, provider?, fallbacks? }`). This is the shared normalization used
+ * for phase buckets so sibling single-model fields — `post_unit_hooks[].model`,
+ * `auto_supervisor.model`, and `reactive_execution.subagent_model` — honor
+ * `fallbacks[]` identically rather than accepting a bare string only (#1229).
+ *
+ * Returns undefined for an unset, blank, or model-less field.
+ */
+export function normalizeModelFieldConfig(field) {
+    if (!field)
+        return undefined;
+    if (typeof field === "string") {
+        return field.trim() ? { primary: field, fallbacks: [] } : undefined;
+    }
+    if (!field.model)
+        return undefined;
+    // When provider is explicitly set, prepend it to the model ID so the
+    // resolution code in auto.ts can do an explicit provider match.
+    const primary = field.provider && !field.model.includes("/")
+        ? `${field.provider}/${field.model}`
+        : field.model;
+    // Carry the per-field `thinking` sub-field through so the dispatch site can
+    // prefer it over the session/floor level, mirroring phase-inline thinking
+    // (#1269). `undefined` is preserved as absent so behavior is unchanged.
+    return {
+        primary,
+        fallbacks: field.fallbacks ?? [],
+        ...(field.thinking ? { thinking: field.thinking } : {}),
+    };
+}
 /**
  * Resolve model and fallbacks for a given auto-mode unit type.
  * Returns the primary model and ordered fallbacks, or undefined if not configured.
@@ -73,6 +106,15 @@ function resolveWinningPhase(models, chain) {
  * Supports both legacy string format and extended object format:
  * - Legacy: `planning: claude-opus-4-6`
  * - Extended: `planning: { model: claude-opus-4-6, fallbacks: [glm-5, minimax-m2.5] }`
+ *
+ * Hook unit types (`hook/<name>`) resolve against the matching
+ * `post_unit_hooks[]` entry's `model` field so hook sessions honor the same
+ * `fallbacks[]` chain as phase buckets — the recovery path can then switch to
+ * a fallback provider instead of hard-failing (and potentially pausing) the
+ * run on a transient provider trip (#1229).
+ *
+ * The synthetic `supervisor` unit type resolves against `auto_supervisor.model`
+ * for supervisor interventions (wrap-up warnings, timeout recovery).
  */
 export function resolveModelWithFallbacksForUnit(unitType, basePath, availableModelIds, preferredModelId, skipProfileDefaults = false) {
     const loadOpts = {
@@ -81,26 +123,25 @@ export function resolveModelWithFallbacksForUnit(unitType, basePath, availableMo
         ...(skipProfileDefaults ? { skipProfileDefaults: true } : {}),
     };
     const prefs = loadEffectiveGSDPreferences(basePath, loadOpts);
+    // Supervisor interventions resolve against `auto_supervisor.model` (#1229).
+    if (unitType === "supervisor") {
+        return normalizeModelFieldConfig(prefs?.preferences?.auto_supervisor?.model);
+    }
+    // Hook sessions resolve against their own `post_unit_hooks[].model` field,
+    // which now shares the phase-bucket object form (#1229).
+    if (unitType.startsWith("hook/")) {
+        const hookName = unitType.slice("hook/".length);
+        const hooks = prefs?.preferences?.post_unit_hooks;
+        const hook = Array.isArray(hooks) ? hooks.find((h) => h.name === hookName) : undefined;
+        return normalizeModelFieldConfig(hook?.model);
+    }
     const chain = phaseChainForUnit(unitType);
     if (!chain)
         return undefined;
     const winner = resolveWinningPhase(prefs?.preferences?.models, chain);
     if (!winner)
         return undefined;
-    const phaseConfig = winner.config;
-    // Normalize: string -> { model, fallbacks: [] }
-    if (typeof phaseConfig === "string") {
-        return { primary: phaseConfig, fallbacks: [] };
-    }
-    // When provider is explicitly set, prepend it to the model ID so the
-    // resolution code in auto.ts can do an explicit provider match.
-    const primary = phaseConfig.provider && !phaseConfig.model.includes("/")
-        ? `${phaseConfig.provider}/${phaseConfig.model}`
-        : phaseConfig.model;
-    return {
-        primary,
-        fallbacks: phaseConfig.fallbacks ?? [],
-    };
+    return normalizeModelFieldConfig(winner.config);
 }
 /**
  * Resolve the explicitly configured reasoning effort for a unit type (ADR-026).
@@ -125,6 +166,13 @@ export function resolveModelWithFallbacksForUnit(unitType, basePath, availableMo
  * applied here.
  */
 export function resolveThinkingLevelForUnit(unitType, basePath, availableModelIds) {
+    // Single-field configs — `auto_supervisor.model` and `post_unit_hooks[].model`
+    // — carry their own inline `thinking` on the object model form and have no
+    // phase-bucket chain, so the walk below never covers them. Resolve their
+    // per-field level directly (#1269).
+    if (unitType === "supervisor" || unitType.startsWith("hook/")) {
+        return resolveModelWithFallbacksForUnit(unitType, basePath, availableModelIds)?.thinking;
+    }
     const loadOpts = availableModelIds !== undefined ? { availableModelIds } : undefined;
     const prefs = loadEffectiveGSDPreferences(basePath, loadOpts)?.preferences;
     if (!prefs)
@@ -383,12 +431,15 @@ export function resolveDynamicRoutingConfig() {
 export function resolveAutoSupervisorConfig() {
     const prefs = loadEffectiveGSDPreferences();
     const configured = prefs?.preferences.auto_supervisor ?? {};
+    const modelConfig = normalizeModelFieldConfig(configured.model);
     return {
         soft_timeout_minutes: configured.soft_timeout_minutes ?? 20,
         idle_timeout_minutes: configured.idle_timeout_minutes ?? 10,
         hard_timeout_minutes: configured.hard_timeout_minutes ?? 30,
         stalled_tool_timeout_minutes: configured.stalled_tool_timeout_minutes ?? 5,
-        ...(configured.model ? { model: configured.model } : {}),
+        ...(modelConfig
+            ? { model: modelConfig.primary, modelFallbacks: modelConfig.fallbacks }
+            : {}),
     };
 }
 // ─── Token Profile Resolution ─────────────────────────────────────────────

package/dist/resources/extensions/gsd/preferences-skills.js

@@ -4,35 +4,29 @@
  * Contains all logic for resolving skill references from preferences
  * to absolute filesystem paths, plus skill discovery and staleness config.
  */
-import { existsSync, readdirSync } from "node:fs";
+import { existsSync, readdirSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
+import { getSkillDirectories } from "@gsd/pi-coding-agent";
 import { gsdHome } from "./gsd-home.js";
-import { statSync } from "node:fs";
 import { validatePreferences } from "./preferences-validation.js";
 /**
  * Known skill directories for **preference reference resolution** (bare skill names).
  *
- * Search order (first match wins):
- * 1. ~/.gsd/agent/skills/ (GSD bundled)
- * 2. ~/.agents/skills/ (ecosystem global)
- * 3. .agents/skills/ (project ecosystem)
- * 4. ~/.claude/skills/ and .claude/skills/ (Claude Code compatibility)
+ * Sourced from the shared taxonomy (`@gsd/pi-coding-agent` `getSkillDirectories`)
+ * so preference resolution, mid-session discovery, and the PackageManager
+ * catalog all agree on which directories exist. The `method` is derived from
+ * each entry's scope.
  *
  * Note: the ResourceLoader catalog uses PackageManager precedence instead —
  * project `.gsd/skills` and `.agents/skills` can override bundled GSD skills
  * on name collision. See docs/dev/what-is-pi/09-the-customization-stack.md.
  */
 export function getSkillSearchDirs(cwd) {
-    const dirs = [
-        { dir: join(gsdHome(), "agent", "skills"), method: "user-skill" },
-        { dir: join(homedir(), ".agents", "skills"), method: "user-skill" },
-        { dir: join(cwd, ".agents", "skills"), method: "project-skill" },
-        // Claude Code official skill directories
-        { dir: join(homedir(), ".claude", "skills"), method: "user-skill" },
-        { dir: join(cwd, ".claude", "skills"), method: "project-skill" },
-    ];
-    return dirs;
+    return getSkillDirectories({ cwd, gsdHome: gsdHome() }).map((entry) => ({
+        dir: entry.path,
+        method: entry.scope === "project" ? "project-skill" : "user-skill",
+    }));
 }
 /**
  * Resolve a single skill reference to an absolute path.

package/dist/resources/extensions/gsd/preferences-types.js

@@ -86,6 +86,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set([
     "min_request_interval_ms",
     "stale_commit_threshold_minutes",
     "context_management",
+    "tool_call_loop_guard",
     "experimental",
     "codebase",
     "slice_parallel",

package/dist/resources/extensions/gsd/preferences-validation.js

@@ -25,6 +25,57 @@ const VALID_UOK_TURN_ACTIONS = new Set([
     "snapshot",
     "status-only",
 ]);
+/**
+ * Sanitize a single model field that accepts either a bare model ID or the
+ * extended `{ model, provider?, fallbacks? }` object form used by phase buckets
+ * (#1229). Returns the sanitized value, or undefined when unset/invalid (in
+ * which case an error describing `label` is pushed onto `errors`).
+ */
+function sanitizeModelField(raw, label, errors, warnings) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw === "string") {
+        const trimmed = raw.trim();
+        if (!trimmed) {
+            errors.push(`${label} must not be an empty string`);
+            return undefined;
+        }
+        return trimmed;
+    }
+    if (raw && typeof raw === "object") {
+        const obj = raw;
+        const model = typeof obj.model === "string" ? obj.model.trim() : "";
+        if (!model) {
+            errors.push(`${label} object form requires a non-empty "model"`);
+            return undefined;
+        }
+        const sanitized = { model };
+        if (typeof obj.provider === "string" && obj.provider.trim()) {
+            sanitized.provider = obj.provider.trim();
+        }
+        if (obj.fallbacks !== undefined) {
+            const fallbacks = normalizeStringArray(obj.fallbacks);
+            if (fallbacks.length > 0)
+                sanitized.fallbacks = fallbacks;
+        }
+        // Preserve the object form's `thinking` sub-field so the dispatch site can
+        // pin the hook/supervisor/subagent reasoning level (#1269). An illegal level
+        // is warned-and-stripped, mirroring inline per-phase thinking, so a typo can't
+        // reach the resolver and be treated as explicit configuration.
+        if (obj.thinking !== undefined) {
+            if (VALID_THINKING_LEVELS.has(obj.thinking)) {
+                sanitized.thinking = obj.thinking;
+            }
+            else {
+                warnings?.push(`${label} thinking "${String(obj.thinking)}" is not a valid thinking level ` +
+                    `(off, minimal, low, medium, high, xhigh) — ignored`);
+            }
+        }
+        return sanitized;
+    }
+    errors.push(`${label} must be a string or an object with a "model" field`);
+    return undefined;
+}
 const VALID_POST_UNIT_HOOK_CRITICALITIES = new Set(["advisory", "blocking"]);
 const VALID_POST_UNIT_HOOK_ON_BLOCK_ACTIONS = new Set([
     "retry-unit",
@@ -452,7 +503,15 @@ export function validatePreferences(preferences) {
     // ─── Auto Supervisor ────────────────────────────────────────────────
     if (preferences.auto_supervisor !== undefined) {
         if (preferences.auto_supervisor && typeof preferences.auto_supervisor === "object") {
-            validated.auto_supervisor = preferences.auto_supervisor;
+            // Validate `model` through the shared sanitizer so the
+            // `{ model, provider?, fallbacks? }` object form is rejected on the same
+            // terms as its post_unit_hooks / reactive_execution siblings (#1229).
+            // Other supervisor fields pass through unchanged.
+            const supervisor = { ...preferences.auto_supervisor };
+            if (supervisor.model !== undefined) {
+                supervisor.model = sanitizeModelField(supervisor.model, "auto_supervisor.model", errors, warnings);
+            }
+            validated.auto_supervisor = supervisor;
         }
         else {
             errors.push("auto_supervisor must be an object");
@@ -548,8 +607,9 @@ export function validatePreferences(preferences) {
                 const mc = typeof hook.max_cycles === "number" ? hook.max_cycles : Number(hook.max_cycles);
                 validHook.max_cycles = Number.isFinite(mc) ? Math.max(1, Math.min(10, Math.round(mc))) : 1;
             }
-            if (typeof hook.model === "string" && hook.model.trim()) {
-                validHook.model = hook.model.trim();
+            const hookModel = sanitizeModelField(hook.model, `post_unit_hooks "${name}" model`, errors, warnings);
+            if (hookModel !== undefined) {
+                validHook.model = hookModel;
             }
             if (typeof hook.artifact === "string" && hook.artifact.trim()) {
                 validHook.artifact = hook.artifact.trim();
@@ -801,6 +861,88 @@ export function validatePreferences(preferences) {
             errors.push("context_management must be an object");
         }
     }
+    // ─── Tool-call loop guard (#1198) ────────────────────────────────────────
+    if (preferences.tool_call_loop_guard !== undefined) {
+        if (typeof preferences.tool_call_loop_guard === "object" && preferences.tool_call_loop_guard !== null) {
+            const g = preferences.tool_call_loop_guard;
+            const validGuard = {};
+            if (g.enabled !== undefined) {
+                if (typeof g.enabled === "boolean")
+                    validGuard.enabled = g.enabled;
+                else
+                    errors.push("tool_call_loop_guard.enabled must be a boolean");
+            }
+            if (g.identical_args !== undefined) {
+                if (typeof g.identical_args === "object" && g.identical_args !== null) {
+                    const ia = g.identical_args;
+                    const validIa = {};
+                    if (ia.enabled !== undefined) {
+                        if (typeof ia.enabled === "boolean")
+                            validIa.enabled = ia.enabled;
+                        else
+                            errors.push("tool_call_loop_guard.identical_args.enabled must be a boolean");
+                    }
+                    if (ia.max_consecutive_calls !== undefined) {
+                        const n = ia.max_consecutive_calls;
+                        if (typeof n === "number" && Number.isInteger(n) && n >= 1)
+                            validIa.max_consecutive_calls = n;
+                        else
+                            errors.push("tool_call_loop_guard.identical_args.max_consecutive_calls must be an integer >= 1");
+                    }
+                    if (Object.keys(validIa).length > 0)
+                        validGuard.identical_args = validIa;
+                }
+                else {
+                    errors.push("tool_call_loop_guard.identical_args must be an object");
+                }
+            }
+            if (g.repeated_tool !== undefined) {
+                if (typeof g.repeated_tool === "object" && g.repeated_tool !== null) {
+                    const rt = g.repeated_tool;
+                    const validRt = {};
+                    if (rt.enabled !== undefined) {
+                        if (typeof rt.enabled === "boolean")
+                            validRt.enabled = rt.enabled;
+                        else
+                            errors.push("tool_call_loop_guard.repeated_tool.enabled must be a boolean");
+                    }
+                    if (rt.default_cap !== undefined) {
+                        const n = rt.default_cap;
+                        if (typeof n === "number" && Number.isInteger(n) && n >= 1)
+                            validRt.default_cap = n;
+                        else
+                            errors.push("tool_call_loop_guard.repeated_tool.default_cap must be an integer >= 1");
+                    }
+                    if (rt.repeatable_cap !== undefined) {
+                        const n = rt.repeatable_cap;
+                        if (typeof n === "number" && Number.isInteger(n) && n >= 1)
+                            validRt.repeatable_cap = n;
+                        else
+                            errors.push("tool_call_loop_guard.repeated_tool.repeatable_cap must be an integer >= 1");
+                    }
+                    if (rt.exempt_tools !== undefined) {
+                        if (Array.isArray(rt.exempt_tools) && rt.exempt_tools.every((t) => typeof t === "string")) {
+                            validRt.exempt_tools = rt.exempt_tools;
+                        }
+                        else {
+                            errors.push("tool_call_loop_guard.repeated_tool.exempt_tools must be an array of strings");
+                        }
+                    }
+                    if (Object.keys(validRt).length > 0)
+                        validGuard.repeated_tool = validRt;
+                }
+                else {
+                    errors.push("tool_call_loop_guard.repeated_tool must be an object");
+                }
+            }
+            if (Object.keys(validGuard).length > 0) {
+                validated.tool_call_loop_guard = validGuard;
+            }
+        }
+        else {
+            errors.push("tool_call_loop_guard must be an object");
+        }
+    }
     // ─── Context Mode (gsd_exec sandbox) ────────────────────────────────────
     if (preferences.context_mode !== undefined) {
         if (typeof preferences.context_mode === "object" && preferences.context_mode !== null) {
@@ -968,13 +1110,9 @@ export function validatePreferences(preferences) {
                     errors.push('reactive_execution.isolation_mode must be "same-tree"');
                 }
             }
-            if (re.subagent_model !== undefined) {
-                if (typeof re.subagent_model === "string" && re.subagent_model.length > 0) {
-                    validRe.subagent_model = re.subagent_model;
-                }
-                else {
-                    errors.push("reactive_execution.subagent_model must be a non-empty string");
-                }
+            const subagentModel = sanitizeModelField(re.subagent_model, "reactive_execution.subagent_model", errors, warnings);
+            if (subagentModel !== undefined) {
+                validRe.subagent_model = subagentModel;
             }
             const knownReKeys = new Set(["enabled", "max_parallel", "isolation_mode", "subagent_model"]);
             for (const key of Object.keys(re)) {

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

@@ -822,6 +822,26 @@ export function renderPreferencesForSystemPrompt(preferences, resolutions, optio
     }
     return lines.join("\n");
 }
+/**
+ * Render a compact response-language directive for injection into dispatched
+ * prompt *content* (discuss/QA and auto-execution unit prompts).
+ *
+ * The main session's system prompt already carries the full GSD Skill
+ * Preferences block (including language) via `before_agent_start`, but
+ * discuss/QA turns and auto-execution units are dispatched as separate
+ * turns/sessions whose prompts are assembled here — without that block — so the
+ * configured language never reaches them (#1210). Injecting this directive into
+ * the dispatched prompt content makes the `language` preference effective across
+ * both guided and auto workflows.
+ *
+ * Returns "" when no language is configured.
+ */
+export function renderLanguageDirectiveForPrompt(preferences) {
+    if (!preferences?.language)
+        return "";
+    const safeLang = preferences.language.replace(/[\r\n]/g, " ").slice(0, 50);
+    return `## Response Language\n\nAlways respond in ${safeLang} — questions, explanations, and summaries.`;
+}
 // ─── Hook Resolution ──────────────────────────────────────────────────────────
 /**
  * Resolve enabled post-unit hooks from effective preferences.

package/dist/resources/extensions/gsd/prompts/system.md

@@ -38,7 +38,7 @@ If a `GSD Skill Preferences` block appears below, treat it as durable guidance f
 
 ### Naming Convention
 
-Directories use bare IDs. Files use ID-SUFFIX format. Milestones: `M001/` or `M{seq}-{rand6}/` when `unique_milestone_ids: true`; files like `M001-CONTEXT.md`, `M001-ROADMAP.md`, `M001-RESEARCH.md`. Slices: `S01/` with `S01-PLAN.md`, `S01-RESEARCH.md`, `S01-SUMMARY.md`, `S01-UAT.md`. Tasks: `T01-PLAN.md`, `T01-SUMMARY.md`. Titles live inside content, not names.
+GSD projects use a flat-phase layout. Phase directories are `{MM}-{slug}` where `{MM}` is the zero-padded phase number and `{slug}` is derived from the phase title (e.g. `47-real-time-runtime-hardening`). Phase-level files are `{MM}-SUFFIX.md` (e.g. `47-CONTEXT.md`, `47-RESEARCH.md`, `47-ROADMAP.md`, `47-VALIDATION.md`, `47-SUMMARY.md`). Slice/plan files live directly in the phase directory as `{MM}-{SS}-SUFFIX.md` (e.g. `47-01-PLAN.md`, `47-01-SUMMARY.md`, `47-01-UAT.md`). Task plan content lives inside the slice plan file (`{MM}-{SS}-PLAN.md`) as checkboxes; there is no `tasks/` subdirectory and no `tasks/T##-PLAN.md`. Titles live inside content, not names. Prefer GSD-provided layout-aware paths/resolvers over hardcoding artifact paths, since phase slugs are title-derived.
 
 ### Directory Structure
 
@@ -46,13 +46,13 @@ Directories use bare IDs. Files use ID-SUFFIX format. Milestones: `M001/` or `M{
 .gsd/
   PROJECT.md, REQUIREMENTS.md, DECISIONS.md, KNOWLEDGE.md, CODEBASE.md, OVERRIDES.md, QUEUE.md, STATE.md
   runtime/, activity/, worktrees/
-  milestones/M001/
-    M001-CONTEXT.md, M001-RESEARCH.md, M001-ROADMAP.md, M001-SUMMARY.md
-    slices/S01/
-      S01-CONTEXT.md, S01-RESEARCH.md, S01-PLAN.md, S01-SUMMARY.md, S01-UAT.md
-      tasks/T01-PLAN.md, tasks/T01-SUMMARY.md
+  phases/{MM}-{slug}/
+    {MM}-CONTEXT.md, {MM}-RESEARCH.md, {MM}-ROADMAP.md, {MM}-VALIDATION.md, {MM}-SUMMARY.md
+    {MM}-{SS}-PLAN.md, {MM}-{SS}-SUMMARY.md, {MM}-{SS}-UAT.md
 ```
 
+Task plan content is embedded in `{MM}-{SS}-PLAN.md`; do not expect `tasks/T##-PLAN.md`.
+
 `runtime/`, `activity/`, `worktrees/`, and `STATE.md` are system-managed. `PROJECT.md` is current state; `REQUIREMENTS.md` is the active capability contract; `DECISIONS.md` and `KNOWLEDGE.md` are append-only; `CODEBASE.md` is an auto-refreshed codebase map.
 
 ### Isolation Model

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

@@ -13,7 +13,7 @@ import { isAbsolute, join, relative, resolve } from "node:path";
 import { QUICK_BRANCH_RE } from "./branch-patterns.js";
 import { loadPrompt } from "./prompt-loader.js";
 import { gsdRoot } from "./paths.js";
-import { GitServiceImpl, runGit } from "./git-service.js";
+import { GitServiceImpl, runGit, taskBranchArgs } from "./git-service.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { nativeBranchExists, nativeDetectMainBranch, nativeDiffNumstat } from "./native-git-bridge.js";
 import { nativeHasStagedChanges } from "./native-git-bridge.js";
@@ -317,6 +317,7 @@ export async function handleQuick(args, ctx, pi) {
     const git = new GitServiceImpl(basePath, gitPrefs);
     const branchName = `gsd/quick/${taskNum}-${slug}`;
     let originalBranch = git.getCurrentBranch();
+    let returnBranch = originalBranch;
     const { getIsolationMode } = await import("./preferences.js");
     const usesBranch = getIsolationMode() !== "none" && isGitOpsEnabled();
     let branchCreated = false;
@@ -331,7 +332,15 @@ export async function handleQuick(args, ctx, pi) {
                     }
                 }
                 catch { /* nothing to commit — fine */ }
-                runGit(basePath, ["checkout", "-b", branchName]);
+                const branchArgs = taskBranchArgs(basePath, branchName, current, git.getMainBranch());
+                const startPoint = branchArgs[3];
+                // When the quick branch is redirected off a stale task branch, the
+                // squash-merge on closeout must return to the same base — merging a
+                // base-branch-rooted quick branch back into the stale task branch
+                // would drag the base's newer history into it.
+                if (startPoint)
+                    returnBranch = startPoint;
+                runGit(basePath, branchArgs);
                 branchCreated = true;
             }
         }
@@ -345,7 +354,7 @@ export async function handleQuick(args, ctx, pi) {
     if (actualBranch === branchName && originalBranch !== branchName) {
         persistPendingReturn({
             basePath,
-            originalBranch,
+            originalBranch: returnBranch,
             quickBranch: branchName,
             taskNum,
             slug,

package/dist/resources/extensions/gsd/reopen-reason.js

@@ -0,0 +1,98 @@
+// Project/App: gsd-pi
+// File Purpose: Persist a reopened task's failure diagnosis and inject it into the re-dispatched execute-task prompt.
+// GSD Extension — follow-up to #1225 (#1272)
+//
+// When complete-slice's gate reopens a task via gsd_task_reopen, the operator
+// supplies a `reason` explaining exactly what the full-suite gate caught and
+// how to fix it. That reason previously only landed in the workflow event log
+// (audit trail) and never reached the re-dispatched executor, so the executor
+// re-ran the original (green) verify and re-completed the task without touching
+// the regression. This module is the "inject unresolved context into the next
+// dispatch" mechanism for reopen reasons — a lightweight, file-based sibling of
+// escalation.js#claimOverrideForInjection, keyed by (milestone, slice, task).
+import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { legacyMilestonesDir, resolveSlicePath, resolveTasksDir } from "./paths.js";
+import { atomicWriteSync } from "./atomic-write.js";
+import { logWarning } from "./workflow-logger.js";
+/**
+ * Canonical reopen-reason artifact path, parallel to T##-SUMMARY.md and
+ * T##-ESCALATION.json:
+ *   .gsd/milestones/{M}/slices/{S}/tasks/{T}-REOPEN.json
+ * Flat-phase: the artifact sits directly in the phase dir. Legacy layouts
+ * without a tasks/ subdir return null (caller degrades gracefully).
+ */
+export function reopenReasonArtifactPath(basePath, milestoneId, sliceId, taskId) {
+    const tDir = resolveTasksDir(basePath, milestoneId, sliceId);
+    if (tDir)
+        return join(tDir, `${taskId}-REOPEN.json`);
+    if (existsSync(legacyMilestonesDir(basePath)))
+        return null;
+    const phaseDir = resolveSlicePath(basePath, milestoneId, sliceId);
+    if (!phaseDir)
+        return null;
+    return join(phaseDir, `${taskId}-REOPEN.json`);
+}
+/**
+ * Persist the reopen reason so the next execute-task dispatch can surface it.
+ * A no-op when the reason is empty or the artifact path cannot be resolved —
+ * reopen itself must still succeed even if we cannot attach context.
+ */
+export function writeReopenReason(basePath, milestoneId, sliceId, taskId, reason) {
+    const trimmed = reason.trim();
+    if (!trimmed)
+        return;
+    const path = reopenReasonArtifactPath(basePath, milestoneId, sliceId, taskId);
+    if (!path) {
+        logWarning("tool", `reopen-reason: cannot resolve artifact path for ${milestoneId}/${sliceId}/${taskId}; reopen reason not attached to next dispatch`);
+        return;
+    }
+    const artifact = {
+        version: 1,
+        milestoneId, sliceId, taskId,
+        reason: trimmed,
+        createdAt: new Date().toISOString(),
+    };
+    mkdirSync(join(path, ".."), { recursive: true });
+    atomicWriteSync(path, JSON.stringify(artifact, null, 2));
+}
+/**
+ * If a reopen reason is pending for this task, claim it (one-shot: the artifact
+ * is deleted on read) and return the markdown block to prepend to the executor's
+ * prompt. Returns null when nothing is pending or the artifact is malformed.
+ */
+export function claimReopenReasonForInjection(basePath, milestoneId, sliceId, taskId) {
+    const path = reopenReasonArtifactPath(basePath, milestoneId, sliceId, taskId);
+    if (!path || !existsSync(path))
+        return null;
+    let art = null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        if (parsed && parsed.version === 1 && typeof parsed.reason === "string" && parsed.reason.trim()) {
+            art = parsed;
+        }
+    }
+    catch {
+        art = null;
+    }
+    // Claim (delete) regardless of validity so a malformed artifact doesn't
+    // wedge every future dispatch of this task.
+    try {
+        unlinkSync(path);
+    }
+    catch { /* already gone */ }
+    if (!art)
+        return null;
+    return { injectionBlock: formatReopenReasonBlock(art) };
+}
+function formatReopenReasonBlock(art) {
+    return [
+        `## Reopened — Reason (from ${art.taskId})`,
+        "",
+        "This task was previously marked complete but a downstream gate (e.g. complete-slice's full-suite run) reopened it. The verify command in your task plan passed in isolation — it did **not** catch the regression below. Do **not** call `gsd_task_complete` until you have reproduced and fixed exactly what this diagnosis describes, then re-run the specific failing command it names (not just the original scoped verify).",
+        "",
+        "**Diagnosis / fix instructions from the gate:**",
+        "",
+        art.reason.trim(),
+    ].join("\n");
+}