@opengsd/gsd-pi 1.4.0 → 1.5.0-dev.553dc518

package/dist/resources/extensions/gsd/redact-secrets.js

@@ -0,0 +1,37 @@
+// redact-secrets.ts
+// Best-effort redaction of secret-shaped substrings before persisting free text
+// (exec-sandbox output, activity-log session entries) to disk under .gsd/, which
+// the secret scanner skips. Patterns mirror scripts/secret-scan.mjs.
+const PLACEHOLDER = "«redacted»";
+// Each secret shape. Global flag so replace() catches every occurrence in a line.
+// Order is not significant — matches are replaced independently.
+const PATTERNS = [
+    /AKIA[0-9A-Z]{16}/g, // AWS access key id
+    /(api[_-]?key|apikey|api[_-]?secret)[ \t]*[:=][ \t]*['"][0-9a-zA-Z_./-]{20,}['"]/gi,
+    /(secret|token|password|passwd|pwd|credential)[ \t]*[:=][ \t]*['"][^\s'"]{8,}['"]/gi,
+    /(authorization|bearer)[ \t]*[:=][ \t]*['"][^\s'"]{8,}['"]/gi,
+    /Bearer[ \t]+[0-9a-zA-Z._-]{8,}/g, // Authorization: Bearer <token> (unquoted)
+    /-----BEGIN\s+(RSA|DSA|EC|OPENSSH|PGP)\s+PRIVATE\s+KEY-----[\s\S]*?-----END\s+(RSA|DSA|EC|OPENSSH|PGP)\s+PRIVATE\s+KEY-----/g,
+    /(mysql|postgres|postgresql|mongodb|redis|amqp|mssql):\/\/[^\s'"]{8,}/gi,
+    /gh[pousr]_[0-9a-zA-Z]{36,}/g, // GitHub token
+    /glpat-[0-9a-zA-Z-]{20,}/g, // GitLab token
+    /xox[baprs]-[0-9a-zA-Z-]{10,}/g, // Slack token
+    /hooks\.slack\.com\/services\/T[0-9A-Z]{8,}\/B[0-9A-Z]{8,}\/[0-9a-zA-Z]{20,}/g,
+    /AIza[0-9A-Za-z_-]{35}/g, // Google API key
+    /[sr]k_(live|test)_[0-9a-zA-Z]{20,}/g, // Stripe key
+    /sk-(ant-)?[0-9a-zA-Z_-]{20,}/g, // OpenAI / Anthropic style key
+    /npm_[0-9a-zA-Z]{36,}/g, // npm token
+    /(secret|key|token|password)[ \t]*[:=][ \t]*['"]?[0-9a-f]{32,}['"]?/gi, // hex secret
+];
+/**
+ * Replace secret-shaped substrings in `text` with a placeholder, preserving the
+ * surrounding content. Pure and safe to call per log line. The placeholder
+ * contains no quote/brace/backslash, so redacting a JSON string keeps it valid.
+ */
+export function redactSecrets(text) {
+    let out = text;
+    for (const pattern of PATTERNS) {
+        out = out.replace(pattern, PLACEHOLDER);
+    }
+    return out;
+}

package/dist/resources/extensions/gsd/repo-identity.js

@@ -328,6 +328,22 @@ export function externalProjectsRoot() {
     const base = process.env.GSD_STATE_DIR || gsdHome();
     return join(base, "projects");
 }
+/**
+ * Check whether this project already has authoritative external state.
+ *
+ * Used by legacy `.gsd/` migration to avoid re-copying a re-materialized local
+ * directory over newer state when an already-migrated symlink was replaced.
+ */
+export function externalStateAlreadyExistsForProject(basePath) {
+    const base = process.env.GSD_STATE_DIR || gsdHome();
+    const computedPath = join(base, "projects", repoIdentity(basePath));
+    if (hasProjectState(computedPath))
+        return true;
+    const markerId = readGsdIdMarker(resolveGitRoot(basePath));
+    if (!markerId)
+        return false;
+    return hasProjectState(join(base, "projects", markerId));
+}
 // ─── Numbered Variant Cleanup ────────────────────────────────────────────────
 /**
  * macOS collision pattern: `.gsd 2`, `.gsd 3`, `.gsd 4`, etc.

package/dist/resources/extensions/gsd/repository-registry.js

@@ -5,6 +5,11 @@ import { isAbsolute, relative, resolve } from "node:path";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 import { resolveGsdPathContract } from "./paths.js";
 export function defaultRepositoryTargets(registry) {
+    // In parent mode, default to the declared child repositories so work is
+    // attributed to the repo it touches — not silently to the root "project".
+    if (registry.mode === "parent") {
+        return registry.repositories.filter((repo) => repo.id !== "project").map((repo) => repo.id);
+    }
     const project = registry.byId.get("project");
     if (project)
         return [project.id];
@@ -51,7 +56,7 @@ function resolveGitWorkingTreeRoot(basePath) {
 export function createRepositoryRegistry(basePath, workspacePrefs) {
     const contract = resolveGsdPathContract(basePath);
     const projectRoot = contract.isWorktree
-        ? resolveGitWorkingTreeRoot(contract.workRoot) ?? contract.projectRoot
+        ? resolveGitWorkingTreeRoot(contract.workRoot) ?? contract.workRoot
         : contract.projectRoot;
     const mode = workspacePrefs?.mode ?? "project";
     const repoMap = new Map();

package/dist/resources/extensions/gsd/root-write-leak-guard.js

@@ -42,12 +42,14 @@ export function captureRootDirtySnapshot(rootPath) {
         if (!line.trim())
             continue;
         const code = line.slice(0, 2);
+        if (code !== "??")
+            continue;
         const path = line.slice(3).replace(/^"|"$/g, "");
         if (!path || isRootRuntimePath(path))
             continue;
         snapshot.set(path, {
             path,
-            status: code.trim() || code,
+            status: code,
             fingerprint: fileFingerprint(rootPath, path),
         });
     }
@@ -58,7 +60,7 @@ export function detectRootWriteLeak(input) {
     const leaked = [];
     for (const entry of after.values()) {
         const prior = input.before?.get(entry.path);
-        if (!prior || prior.status !== entry.status || prior.fingerprint !== entry.fingerprint) {
+        if (!prior || prior.fingerprint !== entry.fingerprint) {
             leaked.push(entry);
         }
     }

package/dist/resources/extensions/gsd/safe-fs.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, cpSync } from "node:fs";
+import { existsSync, mkdirSync, cpSync, statSync } from "node:fs";
 import { dirname } from "node:path";
 import { logWarning } from "./workflow-logger.js";
 /**
@@ -40,7 +40,28 @@ export function safeCopyRecursive(src, dst, opts) {
         return false;
     try {
         mkdirSync(dirname(dst), { recursive: true });
-        cpSync(src, dst, { ...opts, recursive: true });
+        const userFilter = opts?.filter;
+        cpSync(src, dst, {
+            ...opts,
+            recursive: true,
+            filter: (srcPath, dstPath) => {
+                if (existsSync(dstPath)) {
+                    try {
+                        const srcStat = statSync(srcPath);
+                        const dstStat = statSync(dstPath);
+                        if (srcStat.isDirectory() !== dstStat.isDirectory()) {
+                            logWarning("fs", `recursive copy skipped type collision: ${srcPath} → ${dstPath}`);
+                            return false;
+                        }
+                    }
+                    catch (err) {
+                        logWarning("fs", `recursive copy skipped unreadable path: ${srcPath} → ${dstPath}: ${err.message}`);
+                        return false;
+                    }
+                }
+                return userFilter ? userFilter(srcPath, dstPath) : true;
+            },
+        });
         return true;
     }
     catch (err) {

package/dist/resources/extensions/gsd/skills/gsd-headless/SKILL.md

@@ -211,17 +211,15 @@ All state lives in `.gsd/` as markdown files (version-controllable):
 
 ```
 .gsd/
-  milestones/M001/
-    M001-CONTEXT.md      # Requirements, scope, decisions
-    M001-ROADMAP.md      # Slices with tasks, dependencies, checkboxes
-    M001-SUMMARY.md      # Completion summary
-    slices/S01/
-      S01-PLAN.md        # Task list
-      S01-SUMMARY.md     # Slice summary with frontmatter
-      tasks/T01-PLAN.md  # Individual task spec
+  phases/01-foundation/
+    01-CONTEXT.md        # Requirements, scope, decisions
+    01-ROADMAP.md        # Slices with tasks, dependencies, checkboxes
+    01-SUMMARY.md        # Completion summary
+    01-01-PLAN.md        # First slice task list
+    01-01-SUMMARY.md     # First slice summary with frontmatter
 ```
 
-State is derived from files on disk — checkboxes in ROADMAP.md are the source of truth for completion.
+Runtime state is stored in the project-root database; markdown files are reviewable projections written under `.gsd/phases/`. Legacy projects may still resolve to `.gsd/milestones/<MID>/` until migrated.
 
 ## All Headless Commands
 

package/dist/resources/extensions/gsd/skills/gsd-headless/references/commands.md

@@ -22,6 +22,7 @@ All commands can be run via `gsd headless [command]`.
 | `status` | Progress dashboard (TUI overlay — useful interactively, not for parsing) |
 | `visualize` | Workflow visualizer (deps, metrics, timeline) |
 | `history` | Execution history (supports --cost, --phase, --model, limit) |
+| `codebase` | Manage `.gsd/CODEBASE.md`; parent workspaces include declared child repositories under repo-labeled sections |
 
 ## Unit Control
 

package/dist/resources/extensions/gsd/slice-parallel-orchestrator.js

@@ -19,7 +19,8 @@ import { isAbsolute, join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { gsdRoot } from "./paths.js";
 import { createWorktree, worktreePath, removeWorktree } from "./worktree-manager.js";
-import { runWorktreePostCreateHook, syncGsdStateToWorktreeByScope } from "./auto-worktree.js";
+import { syncGsdStateToWorktreeByScope } from "./auto-worktree-sync.js";
+import { runWorktreePostCreateHook } from "./worktree-post-create-hook.js";
 import { createWorkspace, scopeMilestone } from "./workspace.js";
 import { writeSessionStatus, } from "./session-status-io.js";
 import { hasFileConflict } from "./slice-parallel-conflict.js";

package/dist/resources/extensions/gsd/state/derive/from-db.js

@@ -12,6 +12,31 @@ import { countUnmappedActiveRequirements, formatCompletePhaseNextAction } from '
 import { logWarning } from '../../workflow-logger.js';
 import { buildDbUnavailableState, ensureExistingWorkflowDbOpen, getRequestedMilestoneLock, } from './db-open.js';
 const isStatusDone = isClosedStatus;
+function buildProgress(context) {
+    return {
+        milestones: context.milestoneProgress,
+        ...(context.sliceProgress ? { slices: context.sliceProgress } : {}),
+        ...(context.taskProgress ? { tasks: context.taskProgress } : {}),
+    };
+}
+function buildDerivedState(context, phase, nextAction, options = {}) {
+    return {
+        activeMilestone: context.activeMilestone,
+        activeSlice: context.activeSlice ?? null,
+        activeTask: context.activeTask ?? null,
+        phase,
+        recentDecisions: [],
+        blockers: options.blockers ?? [],
+        nextAction,
+        ...(options.lastCompletedMilestone !== undefined
+            ? { lastCompletedMilestone: options.lastCompletedMilestone }
+            : {}),
+        ...(options.includeActiveWorkspace ? { activeWorkspace: undefined } : {}),
+        registry: context.registry,
+        requirements: context.requirements,
+        progress: buildProgress(context),
+    };
+}
 function stripMilestonePrefix(title) {
     return title.replace(/^M\d+(?:-[a-z0-9]{6})?[^:]*:\s*/, '') || title;
 }
@@ -125,103 +150,60 @@ async function buildRegistryAndFindActive(basePath, milestones, completeMileston
 function handleNoActiveMilestone(registry, requirements, milestoneProgress) {
     const pendingEntries = registry.filter(e => e.status === 'pending');
     const parkedEntries = registry.filter(e => e.status === 'parked');
+    const context = {
+        activeMilestone: null,
+        registry,
+        requirements,
+        milestoneProgress,
+    };
     if (pendingEntries.length > 0) {
         const blockerDetails = pendingEntries
             .filter(e => e.dependsOn && e.dependsOn.length > 0)
             .map(e => `${e.id} is waiting on unmet deps: ${e.dependsOn.join(', ')}`);
-        return {
-            activeMilestone: null, activeSlice: null, activeTask: null,
-            phase: 'blocked',
-            recentDecisions: [], blockers: blockerDetails.length > 0
+        return buildDerivedState(context, 'blocked', 'Resolve milestone dependencies before proceeding.', {
+            blockers: blockerDetails.length > 0
                 ? blockerDetails
                 : ['All remaining milestones are dep-blocked but no deps listed — check CONTEXT.md files'],
-            nextAction: 'Resolve milestone dependencies before proceeding.',
-            registry, requirements,
-            progress: { milestones: milestoneProgress },
-        };
+        });
     }
     if (parkedEntries.length > 0) {
         const parkedIds = parkedEntries.map(e => e.id).join(', ');
-        return {
-            activeMilestone: null, activeSlice: null, activeTask: null,
-            phase: 'pre-planning',
-            recentDecisions: [], blockers: [],
-            nextAction: `All remaining milestones are parked (${parkedIds}). Run /gsd unpark <id> or create a new milestone.`,
-            registry, requirements,
-            progress: { milestones: milestoneProgress },
-        };
+        return buildDerivedState(context, 'pre-planning', `All remaining milestones are parked (${parkedIds}). Run /gsd unpark <id> or create a new milestone.`);
     }
     if (registry.length === 0) {
-        return {
-            activeMilestone: null, activeSlice: null, activeTask: null,
-            phase: 'pre-planning',
-            recentDecisions: [], blockers: [],
-            nextAction: 'No milestones found. Run /gsd to create one.',
-            registry: [], requirements,
-            progress: { milestones: { done: 0, total: 0 } },
-        };
+        return buildDerivedState({ ...context, registry: [], milestoneProgress: { done: 0, total: 0 } }, 'pre-planning', 'No milestones found. Run /gsd to create one.');
     }
     const lastEntry = registry[registry.length - 1];
     const unmappedActive = countUnmappedActiveRequirements();
     const completionNote = formatCompletePhaseNextAction(unmappedActive);
-    return {
-        activeMilestone: null,
+    return buildDerivedState(context, 'complete', completionNote, {
         lastCompletedMilestone: lastEntry ? { id: lastEntry.id, title: lastEntry.title } : null,
-        activeSlice: null, activeTask: null,
-        phase: 'complete',
-        recentDecisions: [], blockers: [],
-        nextAction: completionNote,
-        registry, requirements,
-        progress: { milestones: milestoneProgress },
-    };
+    });
 }
 async function handleAllSlicesDone(basePath, activeMilestone, registry, requirements, milestoneProgress, sliceProgress) {
     const validation = getLatestAssessmentByScope(activeMilestone.id, "milestone-validation");
     const verdict = typeof validation?.status === "string" ? validation.status : undefined;
     const validationTerminal = verdict != null && verdict !== "";
+    const context = {
+        activeMilestone,
+        registry,
+        requirements,
+        milestoneProgress,
+        sliceProgress,
+    };
     if (!validationTerminal) {
-        return {
-            activeMilestone, activeSlice: null, activeTask: null,
-            phase: 'validating-milestone',
-            recentDecisions: [], blockers: [],
-            nextAction: `Validate milestone ${activeMilestone.id} before completion.`,
-            registry, requirements,
-            progress: { milestones: milestoneProgress, slices: sliceProgress },
-        };
+        return buildDerivedState(context, 'validating-milestone', `Validate milestone ${activeMilestone.id} before completion.`);
     }
     // All roadmap slices are done (enforced by caller) and verdict is
     // needs-remediation — remediation cannot progress without new slices.
     // Return blocked instead of re-dispatching validate-milestone (#4506).
     if (verdict === 'needs-attention') {
-        return {
-            activeMilestone, activeSlice: null, activeTask: null,
-            phase: 'blocked',
-            recentDecisions: [],
-            blockers: [formatNeedsAttentionBlocker(activeMilestone.id)],
-            nextAction: `Resolve ${activeMilestone.id} validation attention before proceeding.`,
-            registry, requirements,
-            progress: { milestones: milestoneProgress, slices: sliceProgress },
-        };
+        return buildDerivedState(context, 'blocked', `Resolve ${activeMilestone.id} validation attention before proceeding.`, { blockers: [formatNeedsAttentionBlocker(activeMilestone.id)] });
     }
     if (verdict === 'needs-remediation') {
-        return {
-            activeMilestone, activeSlice: null, activeTask: null,
-            phase: 'blocked',
-            recentDecisions: [],
-            blockers: [formatNeedsRemediationBlocker(activeMilestone.id)],
-            nextAction: `Resolve ${activeMilestone.id} remediation before proceeding.`,
-            registry, requirements,
-            progress: { milestones: milestoneProgress, slices: sliceProgress },
-        };
+        return buildDerivedState(context, 'blocked', `Resolve ${activeMilestone.id} remediation before proceeding.`, { blockers: [formatNeedsRemediationBlocker(activeMilestone.id)] });
     }
-    return {
-        activeMilestone, activeSlice: null, activeTask: null,
-        phase: 'completing-milestone',
-        recentDecisions: [], blockers: [],
-        nextAction: `All slices complete in ${activeMilestone.id}. Write milestone summary.`,
-        registry, requirements,
-        progress: { milestones: milestoneProgress, slices: sliceProgress },
-    };
+    return buildDerivedState(context, 'completing-milestone', `All slices complete in ${activeMilestone.id}. Write milestone summary.`);
 }
 function resolveSliceDependencies(activeMilestoneSlices) {
     const doneSliceIds = new Set(activeMilestoneSlices.filter(s => isStatusDone(s.status)).map(s => s.id));
@@ -271,13 +253,12 @@ export async function deriveStateFromDb(basePath, artifactReadRoot = basePath) {
         ? allMilestones.filter(m => m.id === milestoneLock)
         : allMilestones;
     if (milestones.length === 0) {
-        return {
-            activeMilestone: null, activeSlice: null, activeTask: null,
-            phase: 'pre-planning', recentDecisions: [], blockers: [],
-            nextAction: 'No milestones found. Run /gsd to create one.',
-            registry: [], requirements,
-            progress: { milestones: { done: 0, total: 0 } },
-        };
+        return buildDerivedState({
+            activeMilestone: null,
+            registry: [],
+            requirements,
+            milestoneProgress: { done: 0, total: 0 },
+        }, 'pre-planning', 'No milestones found. Run /gsd to create one.');
     }
     const { completeMilestoneIds, parkedMilestoneIds } = buildCompletenessSet(basePath, milestones);
     const registryContext = await buildRegistryAndFindActive(basePath, milestones, completeMilestoneIds, parkedMilestoneIds);
@@ -294,18 +275,20 @@ export async function deriveStateFromDb(basePath, artifactReadRoot = basePath) {
         const nextAction = activeMilestoneHasDraft
             ? `Discuss draft context for milestone ${activeMilestone.id}.`
             : `Plan milestone ${activeMilestone.id}.`;
-        return {
-            activeMilestone, activeSlice: null, activeTask: null,
-            phase, recentDecisions: [], blockers: [],
-            nextAction, registry, requirements,
-            progress: { milestones: milestoneProgress },
-        };
+        return buildDerivedState({ activeMilestone, registry, requirements, milestoneProgress }, phase, nextAction);
     }
     const allSlicesDone = activeMilestoneSlices.every(s => isStatusDone(s.status));
     const sliceProgress = {
         done: activeMilestoneSlices.filter(s => isStatusDone(s.status)).length,
         total: activeMilestoneSlices.length,
     };
+    const sliceStateContext = {
+        activeMilestone,
+        registry,
+        requirements,
+        milestoneProgress,
+        sliceProgress,
+    };
     if (allSlicesDone) {
         return handleAllSlicesDone(basePath, activeMilestone, registry, requirements, milestoneProgress, sliceProgress);
     }
@@ -314,21 +297,9 @@ export async function deriveStateFromDb(basePath, artifactReadRoot = basePath) {
         // If locked slice wasn't found, it returns null but logs warning, we need to return 'blocked'
         const sliceLock = process.env.GSD_PARALLEL_WORKER ? process.env.GSD_SLICE_LOCK : undefined;
         if (sliceLock) {
-            return {
-                activeMilestone, activeSlice: null, activeTask: null,
-                phase: 'blocked', recentDecisions: [], blockers: [`GSD_SLICE_LOCK=${sliceLock} not found in active milestone slices`],
-                nextAction: 'Slice lock references a non-existent slice — check orchestrator dispatch.',
-                registry, requirements,
-                progress: { milestones: milestoneProgress, slices: sliceProgress },
-            };
+            return buildDerivedState(sliceStateContext, 'blocked', 'Slice lock references a non-existent slice — check orchestrator dispatch.', { blockers: [`GSD_SLICE_LOCK=${sliceLock} not found in active milestone slices`] });
         }
-        return {
-            activeMilestone, activeSlice: null, activeTask: null,
-            phase: 'blocked', recentDecisions: [], blockers: ['No slice eligible — check dependency ordering'],
-            nextAction: 'Resolve dependency blockers or plan next slice.',
-            registry, requirements,
-            progress: { milestones: milestoneProgress, slices: sliceProgress },
-        };
+        return buildDerivedState(sliceStateContext, 'blocked', 'Resolve dependency blockers or plan next slice.', { blockers: ['No slice eligible — check dependency ordering'] });
     }
     const { activeSlice } = activeSliceContext;
     const activeSliceRow = activeSliceContext.activeSliceRow;
@@ -338,39 +309,30 @@ export async function deriveStateFromDb(basePath, artifactReadRoot = basePath) {
     // PLAN.md and preference flags are projections/configuration and are
     // deliberately not used to infer whether the slice itself is a sketch.
     if (activeSliceRow?.is_sketch === 1) {
-        return {
-            activeMilestone, activeSlice, activeTask: null,
-            phase: 'refining', recentDecisions: [], blockers: [],
-            nextAction: `Refine sketch slice ${activeSlice.id} (${activeSlice.title}) using prior slice context.`,
-            registry, requirements,
-            progress: { milestones: milestoneProgress, slices: sliceProgress },
-        };
+        return buildDerivedState({ ...sliceStateContext, activeSlice }, 'refining', `Refine sketch slice ${activeSlice.id} (${activeSlice.title}) using prior slice context.`);
     }
     const tasks = getSliceTasks(activeMilestone.id, activeSlice.id);
     const taskProgress = {
         done: tasks.filter(t => isStatusDone(t.status)).length,
         total: tasks.length,
     };
+    const taskStateContext = {
+        ...sliceStateContext,
+        activeSlice,
+        taskProgress,
+    };
     const activeTaskRow = tasks.find(t => !isStatusDone(t.status));
     if (!activeTaskRow && tasks.length > 0) {
-        return {
-            activeMilestone, activeSlice, activeTask: null,
-            phase: 'summarizing', recentDecisions: [], blockers: [],
-            nextAction: `All tasks done in ${activeSlice.id}. Write slice summary and complete slice.`,
-            registry, requirements,
-            progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
-        };
+        return buildDerivedState(taskStateContext, 'summarizing', `All tasks done in ${activeSlice.id}. Write slice summary and complete slice.`);
     }
     if (!activeTaskRow) {
-        return {
-            activeMilestone, activeSlice, activeTask: null,
-            phase: 'planning', recentDecisions: [], blockers: [],
-            nextAction: `Slice ${activeSlice.id} has no DB tasks. Plan slice tasks before execution.`,
-            registry, requirements,
-            progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
-        };
+        return buildDerivedState(taskStateContext, 'planning', `Slice ${activeSlice.id} has no DB tasks. Plan slice tasks before execution.`);
     }
     const activeTask = { id: activeTaskRow.id, title: activeTaskRow.title };
+    const activeTaskStateContext = {
+        ...taskStateContext,
+        activeTask,
+    };
     // ── Quality gate evaluation check ──────────────────────────────────
     // Pause before execution only when gates owned by the `gate-evaluate`
     // turn (Q3/Q4) are still pending. Q8 is also `scope:"slice"` but is
@@ -380,27 +342,16 @@ export async function deriveStateFromDb(basePath, artifactReadRoot = basePath) {
     // Slices with zero gate rows (pre-feature or simple) skip straight through.
     const pendingGateCount = getPendingGateCountForTurn(activeMilestone.id, activeSlice.id, "gate-evaluate");
     if (pendingGateCount > 0) {
-        return {
-            activeMilestone, activeSlice, activeTask: null,
-            phase: 'evaluating-gates', recentDecisions: [], blockers: [],
-            nextAction: `Evaluate ${pendingGateCount} quality gate(s) for ${activeSlice.id} before execution.`,
-            registry, requirements,
-            progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
-        };
+        return buildDerivedState(taskStateContext, 'evaluating-gates', `Evaluate ${pendingGateCount} quality gate(s) for ${activeSlice.id} before execution.`);
     }
     const blockerTaskId = await detectBlockers(basePath, activeMilestone.id, activeSlice.id, tasks);
     if (blockerTaskId) {
         const replanHistory = getReplanHistory(activeMilestone.id, activeSlice.id);
         if (replanHistory.length === 0) {
-            return {
-                activeMilestone, activeSlice, activeTask,
-                phase: 'replanning-slice', recentDecisions: [],
+            return buildDerivedState(activeTaskStateContext, 'replanning-slice', `Task ${blockerTaskId} reported blocker_discovered. Replan slice ${activeSlice.id} before continuing.`, {
                 blockers: [`Task ${blockerTaskId} discovered a blocker requiring slice replan`],
-                nextAction: `Task ${blockerTaskId} reported blocker_discovered. Replan slice ${activeSlice.id} before continuing.`,
-                activeWorkspace: undefined,
-                registry, requirements,
-                progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
-            };
+                includeActiveWorkspace: true,
+            });
         }
     }
     // ADR-011 Phase 2: pause-on-escalation takes precedence over dispatching the
@@ -415,38 +366,22 @@ export async function deriveStateFromDb(basePath, artifactReadRoot = basePath) {
     // and the user's prior resolution never lands.
     const escalatingTaskId = detectPendingEscalation(tasks, basePath);
     if (escalatingTaskId) {
-        return {
-            activeMilestone, activeSlice, activeTask,
-            phase: 'escalating-task', recentDecisions: [],
+        return buildDerivedState(activeTaskStateContext, 'escalating-task', `Run /gsd escalate show ${escalatingTaskId} to review, then /gsd escalate resolve ${escalatingTaskId} <choice> to proceed.`, {
             blockers: [`Task ${escalatingTaskId} requires a user decision before the loop can proceed`],
-            nextAction: `Run /gsd escalate show ${escalatingTaskId} to review, then /gsd escalate resolve ${escalatingTaskId} <choice> to proceed.`,
-            activeWorkspace: undefined,
-            registry, requirements,
-            progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
-        };
+            includeActiveWorkspace: true,
+        });
     }
     if (!blockerTaskId) {
         const isTriggered = checkReplanTrigger(basePath, activeMilestone.id, activeSlice.id);
         if (isTriggered) {
             const replanHistory = getReplanHistory(activeMilestone.id, activeSlice.id);
             if (replanHistory.length === 0) {
-                return {
-                    activeMilestone, activeSlice, activeTask,
-                    phase: 'replanning-slice', recentDecisions: [],
+                return buildDerivedState(activeTaskStateContext, 'replanning-slice', `Triage replan triggered for slice ${activeSlice.id}. Replan before continuing.`, {
                     blockers: ['Triage replan trigger detected — slice replan required'],
-                    nextAction: `Triage replan triggered for slice ${activeSlice.id}. Replan before continuing.`,
-                    activeWorkspace: undefined,
-                    registry, requirements,
-                    progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
-                };
+                    includeActiveWorkspace: true,
+                });
             }
         }
     }
-    return {
-        activeMilestone, activeSlice, activeTask,
-        phase: 'executing', recentDecisions: [], blockers: [],
-        nextAction: `Execute ${activeTask.id}: ${activeTask.title} in slice ${activeSlice.id}.`,
-        registry, requirements,
-        progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
-    };
+    return buildDerivedState(activeTaskStateContext, 'executing', `Execute ${activeTask.id}: ${activeTask.title} in slice ${activeSlice.id}.`);
 }

package/dist/resources/extensions/gsd/tool-contract.js

@@ -26,6 +26,20 @@ export function getUnitWorkflowDispatchReadinessError(input) {
         activeTools: input.activeTools,
     });
 }
+export function getUnitWorkflowDispatchReadinessErrorForModel(input) {
+    const provider = input.model?.provider ?? input.fallbackModel?.provider;
+    const baseUrl = input.model?.baseUrl ?? input.fallbackModel?.baseUrl;
+    return getUnitWorkflowDispatchReadinessError({
+        provider,
+        unitType: input.unitType,
+        projectRoot: input.projectRoot,
+        env: input.env,
+        surface: input.surface,
+        authMode: provider ? input.getProviderAuthMode?.(provider) : undefined,
+        baseUrl,
+        activeTools: input.activeTools,
+    });
+}
 export function compileUnitToolContract(unitType) {
     const manifest = resolveManifest(unitType);
     const surfaceContract = getUnitToolSurfaceContract(unitType);