@opengsd/gsd-pi 1.2.0-dev.4c756166 → 1.2.0-dev.5457a158

package/dist/resources/extensions/gsd/unit-tool-contracts.js

@@ -1,187 +1,14 @@
 // Project/App: gsd-pi
-// File Purpose: Central Unit-to-tool contracts for phase-aware GSD tool surfaces.
-export const RUN_UAT_WORKFLOW_TOOL_NAMES = [
-    "gsd_uat_exec",
-    "gsd_uat_result_save",
-    "gsd_resume",
-    "gsd_milestone_status",
-    "gsd_journal_query",
-];
-export const RUN_UAT_READ_ONLY_TOOL_NAMES = [
-    "find",
-    "glob",
-    "grep",
-    "ls",
-    "read",
-];
-export const RUN_UAT_BROWSER_TOOL_NAMES = [
-    "browser_navigate",
-    "browser_click",
-    "browser_type",
-    "browser_fill_form",
-    "browser_click_ref",
-    "browser_fill_ref",
-    "browser_wait_for",
-    "browser_assert",
-    "browser_verify",
-    "browser_screenshot",
-    "browser_snapshot_refs",
-    "browser_find",
-    "browser_get_console_logs",
-    "browser_get_network_logs",
-    "browser_evaluate",
-    "browser_reload",
-    "browser_batch",
-    "browser_act",
-];
+// File Purpose: Unit-to-tool contract views derived from the Unit Registry (ADR-033).
+//
+// The contract data lives in unit-registry.ts (one Unit Descriptor per unit
+// type). This file keeps the established import surface: the derived
+// `UNIT_TOOL_CONTRACTS` table and its accessor functions are unchanged for
+// consumers.
+import { UNIT_REGISTRY, } from "./unit-registry.js";
+export { RUN_UAT_WORKFLOW_TOOL_NAMES, RUN_UAT_READ_ONLY_TOOL_NAMES, RUN_UAT_BROWSER_TOOL_NAMES, } from "./unit-registry.js";
 export const RUN_UAT_TOOL_PRESENTATION_PLAN_ID = "run-uat/default-v1";
-export const UNIT_TOOL_CONTRACTS = {
-    "research-milestone": {
-        allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
-        requiredWorkflowTools: ["gsd_summary_save"],
-    },
-    "plan-milestone": {
-        allowedGsdTools: [
-            "gsd_milestone_status",
-            "gsd_plan_milestone",
-            "gsd_plan_slice",
-            "gsd_decision_save",
-            "gsd_requirement_update",
-        ],
-        requiredWorkflowTools: ["gsd_milestone_status", "gsd_plan_milestone", "gsd_plan_slice"],
-    },
-    "discuss-milestone": {
-        allowedGsdTools: [
-            "gsd_summary_save",
-            "gsd_decision_save",
-            "gsd_requirement_save",
-            "gsd_requirement_update",
-            "gsd_plan_milestone",
-            "gsd_milestone_generate_id",
-        ],
-        requiredWorkflowTools: [
-            "ask_user_questions",
-            "gsd_summary_save",
-            "gsd_requirement_save",
-            "gsd_requirement_update",
-            "gsd_plan_milestone",
-            "gsd_milestone_generate_id",
-        ],
-    },
-    "discuss-slice": {
-        allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
-        requiredWorkflowTools: ["ask_user_questions", "gsd_summary_save"],
-    },
-    "validate-milestone": {
-        allowedGsdTools: ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap", "subagent"],
-        requiredWorkflowTools: ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap"],
-    },
-    "complete-milestone": {
-        allowedGsdTools: [
-            "gsd_milestone_status",
-            "gsd_requirement_update",
-            "gsd_summary_save",
-            "gsd_complete_milestone",
-            "subagent",
-        ],
-        requiredWorkflowTools: [
-            "gsd_milestone_status",
-            "gsd_requirement_update",
-            "gsd_summary_save",
-            "gsd_complete_milestone",
-        ],
-    },
-    "research-slice": {
-        allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
-        requiredWorkflowTools: ["gsd_summary_save"],
-    },
-    "plan-slice": {
-        allowedGsdTools: ["gsd_plan_slice", "gsd_reassess_roadmap", "gsd_decision_save"],
-        requiredWorkflowTools: ["gsd_plan_slice", "gsd_reassess_roadmap"],
-    },
-    "refine-slice": {
-        allowedGsdTools: ["gsd_plan_slice", "gsd_decision_save"],
-        requiredWorkflowTools: ["gsd_plan_slice"],
-    },
-    "replan-slice": {
-        allowedGsdTools: ["gsd_replan_slice", "gsd_decision_save"],
-        requiredWorkflowTools: ["gsd_replan_slice"],
-    },
-    "complete-slice": {
-        allowedGsdTools: [
-            "gsd_slice_complete",
-            "gsd_task_reopen",
-            "gsd_replan_slice",
-            "gsd_decision_save",
-            "gsd_requirement_update",
-            "gsd_summary_save",
-            "subagent",
-        ],
-        requiredWorkflowTools: [
-            "gsd_slice_complete",
-            "gsd_task_reopen",
-            "gsd_replan_slice",
-            "gsd_requirement_update",
-            "gsd_summary_save",
-        ],
-        forbiddenGsdTools: {
-            gsd_uat_result_save: "Run UAT owns persisted UAT Assessment.",
-        },
-    },
-    "reassess-roadmap": {
-        allowedGsdTools: ["gsd_milestone_status", "gsd_reassess_roadmap"],
-        requiredWorkflowTools: ["gsd_milestone_status", "gsd_reassess_roadmap"],
-    },
-    "execute-task": {
-        allowedGsdTools: ["gsd_task_complete", "gsd_decision_save"],
-        requiredWorkflowTools: ["gsd_task_complete"],
-    },
-    "execute-task-simple": {
-        allowedGsdTools: ["gsd_task_complete", "gsd_decision_save"],
-        requiredWorkflowTools: ["gsd_task_complete"],
-    },
-    "reactive-execute": {
-        allowedGsdTools: ["gsd_task_complete", "gsd_summary_save", "gsd_decision_save"],
-        requiredWorkflowTools: ["gsd_task_complete", "gsd_summary_save"],
-    },
-    "run-uat": {
-        allowedGsdTools: [...RUN_UAT_WORKFLOW_TOOL_NAMES, "subagent"],
-        requiredWorkflowTools: [...RUN_UAT_WORKFLOW_TOOL_NAMES],
-        forbiddenGsdTools: {
-            gsd_exec: "Use gsd_uat_exec so acceptance evidence is typed as UAT-owned.",
-            gsd_save_gate_result: "gsd_uat_result_save owns the aggregate UAT gate.",
-            gsd_summary_save: "gsd_uat_result_save owns persisted UAT Assessment writes.",
-        },
-    },
-    "gate-evaluate": {
-        allowedGsdTools: ["gsd_save_gate_result"],
-        requiredWorkflowTools: ["gsd_save_gate_result"],
-    },
-    "rewrite-docs": {
-        allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
-        requiredWorkflowTools: [],
-    },
-    "workflow-preferences": {
-        allowedGsdTools: ["gsd_summary_save"],
-        requiredWorkflowTools: [],
-    },
-    "discuss-project": {
-        allowedGsdTools: ["gsd_summary_save", "gsd_decision_save", "gsd_requirement_save"],
-        requiredWorkflowTools: ["ask_user_questions", "gsd_summary_save"],
-    },
-    "discuss-requirements": {
-        allowedGsdTools: ["gsd_requirement_save", "gsd_summary_save"],
-        requiredWorkflowTools: ["ask_user_questions", "gsd_requirement_save", "gsd_summary_save"],
-    },
-    "research-decision": {
-        allowedGsdTools: ["gsd_summary_save"],
-        requiredWorkflowTools: ["ask_user_questions"],
-    },
-    "research-project": {
-        allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
-        requiredWorkflowTools: [],
-    },
-};
+export const UNIT_TOOL_CONTRACTS = Object.fromEntries(Object.entries(UNIT_REGISTRY).flatMap(([unitType, descriptor]) => descriptor.toolContract ? [[unitType, descriptor.toolContract]] : []));
 export const AUTO_UNIT_SCOPED_TOOLS = Object.fromEntries(Object.entries(UNIT_TOOL_CONTRACTS).map(([unitType, contract]) => [unitType, contract.allowedGsdTools]));
 export function getUnitToolSurfaceContract(unitType) {
     return UNIT_TOOL_CONTRACTS[unitType];

package/dist/resources/extensions/gsd/workflow-tool-surface.js

@@ -8,7 +8,7 @@ export const WORKFLOW_TOOL_ALIAS_NAMES = CONTRACT_WORKFLOW_TOOL_ALIAS_NAMES;
 export const DB_WORKFLOW_TOOL_NAMES = CONTRACT_WORKFLOW_TOOL_NAMES;
 export const WORKFLOW_TOOL_ALIAS_PAIRS = WORKFLOW_TOOL_CONTRACTS.flatMap((tool) => tool.aliases.map((alias) => ({ canonical: tool.canonicalName, alias })));
 export const WORKFLOW_TOOL_ALIAS_TO_CANONICAL = Object.fromEntries(WORKFLOW_TOOL_ALIAS_PAIRS.map(({ alias, canonical }) => [alias, canonical]));
-const WORKFLOW_MCP_ADAPTER_TOOL_NAMES = [
+export const WORKFLOW_MCP_ADAPTER_TOOL_NAMES = [
     "gsd_cancel",
     "gsd_captures",
     "ask_user_questions",

package/dist/resources/extensions/gsd/worktree-git-recovery.js

@@ -0,0 +1,293 @@
+// Project/App: gsd-pi
+// File Purpose: Git checkout/stash/merge-state recovery primitives for worktree operations.
+/**
+ * Worktree Git Recovery — the recurring-bug hot spot, in one place.
+ *
+ * Owns the verbs that recover a repository from interrupted or conflicting
+ * git operations during worktree transitions:
+ *
+ *   - `checkoutBranchWithStashGuard` — branch switch with stash protection,
+ *     including the stash-pop EEXIST collision recovery for untracked files
+ *     (force-checkout + targeted stash drop; #645 broadened it beyond `.gsd/`,
+ *     guarded by "no non-.gsd unmerged entries remain").
+ *   - `removeMergeStateFiles` — clears SQUASH_MSG / MERGE_HEAD / etc. left by
+ *     a failed merge so subsequent merges don't fail on stale state.
+ *   - `cleanupConflictState` — merge-abort + index reset + state-file cleanup
+ *     after a conflicted (including squash) merge.
+ *   - stash helpers (`popStashByRef`, `stashRefFromError`,
+ *     `stashAlreadyExistsFilesFromError`, `gsdJsonlFilesWithConflictMarkers`)
+ *     used by the merge pipeline in auto-worktree.ts.
+ *
+ * Extracted from auto-worktree.ts so recovery fixes land here instead of as
+ * embedded special cases in a 2,600-line orchestration module, and so the
+ * rules can be tested against scripted git states.
+ *
+ * The State Reconciliation drift repair (`state-reconciliation/drift/
+ * merge-state.ts`) keeps its own merge-state primitive by design — drift
+ * repairs own their raw primitives (see CONTEXT.md, Drift repair).
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { debugLog } from "./debug-logger.js";
+import { logError, logWarning } from "./workflow-logger.js";
+import { nativeAddPaths, nativeCheckoutBranch, nativeConflictFiles, nativeLsFiles, nativeMergeAbort, nativeWorkingTreeStatus, } from "./native-git-bridge.js";
+import { resolveGitDir } from "./worktree-manager.js";
+/**
+ * Pop the stash entry created with `stashMarker` in its subject, resolving it
+ * to a concrete `stash@{n}` ref first so a concurrent stash push cannot make
+ * `git stash pop` grab the wrong entry.
+ *
+ * If `stashMarker` is null or no longer present in the stash list (e.g. a
+ * concurrent process popped/dropped it), leaves the stash list untouched and
+ * returns null.
+ *
+ * Throws on pop failure so callers can handle conflict cases the same way
+ * they would with the prior `git stash pop` form. When throwing after a
+ * targeted pop attempt, the error is annotated with the targeted stash ref.
+ *
+ * (Issue #4980 HIGH-6)
+ */
+export function popStashByRef(basePath, stashMarker) {
+    let popArg = null;
+    if (stashMarker) {
+        try {
+            const list = execFileSync("git", ["stash", "list", "--format=%gd%x00%s"], {
+                cwd: basePath,
+                stdio: ["ignore", "pipe", "pipe"],
+                encoding: "utf-8",
+            }).trim().split("\n").filter(Boolean);
+            for (const entry of list) {
+                const [ref, subject] = entry.split("\0");
+                if (ref && subject?.includes(stashMarker)) {
+                    popArg = ref;
+                    break;
+                }
+            }
+        }
+        catch (err) {
+            logWarning("worktree", `stash list lookup failed; leaving stash untouched: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if (!popArg) {
+        logWarning("worktree", "recorded stash entry could not be resolved; skipping automatic pop");
+        return null;
+    }
+    try {
+        execFileSync("git", ["stash", "pop", popArg], {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+        });
+    }
+    catch (err) {
+        if (err && typeof err === "object") {
+            err.stashRef = popArg;
+        }
+        throw err;
+    }
+    return popArg;
+}
+/**
+ * Extract a stash ref annotation injected by popStashByRef() when git stash
+ * pop fails and we need to conditionally drop the exact stash entry later.
+ */
+export function stashRefFromError(err) {
+    if (!err || typeof err !== "object")
+        return null;
+    const stashRef = err.stashRef;
+    return typeof stashRef === "string" && stashRef.length > 0 ? stashRef : null;
+}
+export function stashAlreadyExistsFilesFromError(err) {
+    if (!err || typeof err !== "object")
+        return [];
+    const stderr = err.stderr;
+    const stderrText = typeof stderr === "string"
+        ? stderr
+        : stderr instanceof Uint8Array
+            ? Buffer.from(stderr).toString("utf-8")
+            : "";
+    const message = err instanceof Error ? err.message : String(err);
+    const text = `${stderrText}\n${message}`;
+    const files = new Set();
+    for (const line of text.split("\n")) {
+        const m = line.match(/^(.*?)\s+already exists, no checkout\s*$/i);
+        if (!m)
+            continue;
+        const filePath = m[1]?.trim();
+        if (filePath)
+            files.add(filePath);
+    }
+    return [...files];
+}
+/**
+ * Detect whether an on-disk file still contains unresolved merge conflict
+ * markers from a failed stash-pop or merge attempt.
+ *
+ * Returns false when the file cannot be read.
+ */
+export function hasConflictMarkers(filePath) {
+    try {
+        const content = readFileSync(filePath, "utf-8");
+        return content.includes("<<<<<<<") && content.includes("=======") && content.includes(">>>>>>>");
+    }
+    catch {
+        return false;
+    }
+}
+export function gsdJsonlFilesWithConflictMarkers(basePath) {
+    return nativeLsFiles(basePath, ".gsd/*.jsonl").filter((f) => hasConflictMarkers(join(basePath, f)));
+}
+export function removeMergeStateFiles(basePath, contextLabel) {
+    try {
+        for (const f of ["SQUASH_MSG", "MERGE_MSG", "MERGE_MODE", "MERGE_HEAD", "AUTO_MERGE"]) {
+            const rawPath = execFileSync("git", ["rev-parse", "--git-path", f], {
+                cwd: basePath,
+                stdio: ["ignore", "pipe", "pipe"],
+                encoding: "utf-8",
+            }).trim();
+            const p = rawPath.length > 0
+                ? (isAbsolute(rawPath) ? rawPath : resolve(basePath, rawPath))
+                : join(resolveGitDir(basePath), f);
+            if (existsSync(p))
+                unlinkSync(p);
+        }
+    }
+    catch (err) {
+        logError("worktree", `${contextLabel} merge state cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+export function cleanupConflictState(basePath) {
+    // Merge conflicts can leave unmerged index entries; merge-abort alone is not
+    // enough for squash merges (MERGE_HEAD is never written). Reset the merge
+    // index, then remove merge message files that native/libgit2 paths may have
+    // created.
+    try {
+        nativeMergeAbort(basePath);
+    }
+    catch (err) {
+        // MERGE_HEAD absent (squash merge path) — abort is a no-op, which is fine.
+        debugLog("conflict-cleanup:merge-abort-skipped", {
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+    try {
+        execFileSync("git", ["reset", "--merge"], {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+        });
+    }
+    catch (err) {
+        logError("worktree", `git reset --merge failed after merge conflict: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    removeMergeStateFiles(basePath, "conflict");
+}
+export function checkoutBranchWithStashGuard(basePath, branch, reason) {
+    let stashMarker = null;
+    let stashed = false;
+    const status = nativeWorkingTreeStatus(basePath).trim();
+    if (status.length > 0) {
+        stashMarker = `gsd-checkout-stash:${reason}:${process.pid}:${Date.now()}:${process.hrtime.bigint().toString(36)}`;
+        const stashListBefore = execFileSync("git", ["stash", "list"], {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+        });
+        execFileSync("git", ["stash", "push", "--include-untracked", "-m", `gsd: checkout stash [${stashMarker}]`], {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+        });
+        const stashListAfter = execFileSync("git", ["stash", "list"], {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+        });
+        stashed = stashListAfter !== stashListBefore;
+    }
+    // Checkout and stash-restore are split so we can distinguish two failure
+    // modes: (a) checkout failed → HEAD did not move, restore stash and rethrow;
+    // (b) checkout succeeded but stash pop failed → HEAD moved to `branch` but
+    // the working-tree changes remain in the stash list. We surface a distinct
+    // error in case (b) so callers don't assume the branch switch was rolled back.
+    try {
+        nativeCheckoutBranch(basePath, branch);
+    }
+    catch (checkoutErr) {
+        if (stashed) {
+            try {
+                popStashByRef(basePath, stashMarker);
+            }
+            catch (restoreErr) {
+                logWarning("worktree", `git stash pop failed during checkout restore: ${restoreErr instanceof Error ? restoreErr.message : String(restoreErr)}`);
+            }
+        }
+        throw checkoutErr;
+    }
+    if (stashed) {
+        try {
+            popStashByRef(basePath, stashMarker);
+        }
+        catch (popErr) {
+            const msg = popErr instanceof Error ? popErr.message : String(popErr);
+            const stderr = popErr && typeof popErr === "object"
+                ? popErr.stderr
+                : undefined;
+            const stderrText = typeof stderr === "string"
+                ? stderr
+                : stderr instanceof Uint8Array
+                    ? Buffer.from(stderr).toString("utf-8")
+                    : "";
+            const stashPopMessage = `${stderrText}\n${msg}`.trim();
+            const alreadyExists = stashAlreadyExistsFilesFromError(popErr);
+            const isUntrackedRestoreFailure = stashPopMessage.includes("could not restore untracked files from stash");
+            const stashRefForDrop = stashRefFromError(popErr);
+            const allConflictFiles = nativeConflictFiles(basePath);
+            const nonGsdUnmerged = allConflictFiles.filter((f) => !f.startsWith(".gsd/"));
+            const gsdUnmerged = allConflictFiles.filter((f) => f.startsWith(".gsd/"));
+            const gsdContentConflicts = isUntrackedRestoreFailure
+                ? gsdJsonlFilesWithConflictMarkers(basePath)
+                : [];
+            // Resolve ALL untracked-collision files by accepting HEAD — files in
+            // alreadyExists were untracked on the source branch by definition of the
+            // "already exists, no checkout" failure, so target HEAD is authoritative.
+            // gsdUnmerged: .gsd/ index conflicts left by the partial stash pop are
+            // also resolved via HEAD — .gsd/ runtime state is always authoritative
+            // on the target branch, so accepting HEAD is safe here too.
+            const resolvable = [...new Set([...alreadyExists, ...gsdContentConflicts, ...gsdUnmerged])];
+            if (isUntrackedRestoreFailure &&
+                resolvable.length > 0 &&
+                nonGsdUnmerged.length === 0) {
+                for (const f of resolvable) {
+                    execFileSync("git", ["checkout", "HEAD", "--", f], {
+                        cwd: basePath,
+                        stdio: ["ignore", "pipe", "pipe"],
+                        encoding: "utf-8",
+                    });
+                    nativeAddPaths(basePath, [f]);
+                }
+                if (stashRefForDrop) {
+                    try {
+                        execFileSync("git", ["stash", "drop", stashRefForDrop], {
+                            cwd: basePath,
+                            stdio: ["ignore", "pipe", "pipe"],
+                            encoding: "utf-8",
+                        });
+                    }
+                    catch (err) { /* stash may already be consumed */
+                        logWarning("worktree", `git stash drop failed: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                }
+                else {
+                    logWarning("worktree", "recorded stash entry could not be resolved; skipping automatic drop");
+                }
+                return;
+            }
+            const wrapped = new Error(`checkout to '${branch}' succeeded but stash restore failed; working tree changes remain in the stash list. Original error: ${msg}`);
+            if (stashRefForDrop)
+                wrapped.stashRef = stashRefForDrop;
+            throw wrapped;
+        }
+    }
+}

package/dist/resources/extensions/gsd/worktree-lifecycle.js

@@ -327,7 +327,15 @@ export function _enterMilestoneCore(s, deps, milestoneId, ctx, opts = {}) {
     // Handles the case where originalBasePath is falsy and basePath is itself
     // a worktree path — prevents double-nested worktree paths (#3729).
     const basePath = resolveWorktreeProjectRoot(s.basePath, s.originalBasePath);
-    const mode = opts.modeOverride ?? getIsolationMode(basePath);
+    // A stranded-recovery session that adopted the milestone branch in the
+    // project root must keep re-entering in that mode: the root checkout holds
+    // the branch, so creating the canonical worktree would fail with "already
+    // in use by another worktree". The override clears when the recovered
+    // milestone merges (_mergeAndExit), restoring configured isolation for
+    // subsequent milestones.
+    const mode = opts.modeOverride ??
+        s.strandedRecoveryIsolationMode ??
+        getIsolationMode(basePath);
     if (s.isolationDegraded) {
         if (mode === "worktree") {
             try {