@opengsd/gsd-pi 1.4.0-dev.5fc22c6f → 1.4.0-dev.c18009cd

package/src/resources/extensions/gsd/unit-registry.ts

@@ -20,8 +20,9 @@
 //
 // Not yet declared here (remaining ADR-033 steps): the manifest data
 // (`UNIT_MANIFESTS` stays in unit-context-manifest.ts, already type-enforced
-// against the registry's `UnitType`) and prompt-template association (still
-// implicit in auto-prompts.ts builders).
+// against the registry's `UnitType`). Prompt-template association is declared
+// for direct one-template units; conditional/composite prompt selection stays
+// with the prompt builders until it has a richer registry shape.
 
 import type { CanonicalWorkflowToolName } from "@opengsd/contracts";
 import { BROWSER_CONTRACT_TOOL_NAMES } from "../shared/browser-contract.js";
@@ -61,6 +62,12 @@ export interface UnitDescriptor {
    * resolves against session defaults).
    */
   readonly phaseChain: readonly GSDModelPhaseKey[] | null;
+  /**
+   * Prompt template id passed to loadPrompt for units with a direct
+   * one-template builder. Omitted for conditional, composite, or not-yet
+   * verified prompt associations.
+   */
+  readonly promptTemplate?: string;
   /** `null` = the unit has no scoped gsd-tool contract. */
   readonly toolContract: UnitToolSurfaceContract | null;
 }
@@ -97,6 +104,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["research"],
+    promptTemplate: "research-milestone",
     toolContract: {
       allowedGsdTools: [
         "gsd_summary_save",
@@ -112,6 +120,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["planning"],
+    promptTemplate: "plan-milestone",
     toolContract: {
       allowedGsdTools: [
         "gsd_milestone_status",
@@ -160,6 +169,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "section-close",
     phaseChain: ["validation", "planning"],
+    promptTemplate: "validate-milestone",
     toolContract: {
       allowedGsdTools: [
         "gsd_milestone_status",
@@ -177,6 +187,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["completion"],
+    promptTemplate: "complete-milestone",
     toolContract: {
       allowedGsdTools: [
         "gsd_milestone_status",
@@ -200,6 +211,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["research"],
+    promptTemplate: "research-slice",
     toolContract: {
       allowedGsdTools: [
         "gsd_milestone_status",
@@ -216,6 +228,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["planning"],
+    promptTemplate: "plan-slice",
     toolContract: {
       allowedGsdTools: [
         "gsd_milestone_status",
@@ -234,6 +247,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["planning"],
+    promptTemplate: "refine-slice",
     toolContract: {
       allowedGsdTools: [
         "gsd_milestone_status",
@@ -250,6 +264,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["planning"],
+    promptTemplate: "replan-slice",
     toolContract: {
       allowedGsdTools: ["gsd_replan_slice", "gsd_decision_save"],
       requiredWorkflowTools: ["gsd_replan_slice"],
@@ -259,6 +274,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "section-close",
     phaseChain: ["completion"],
+    promptTemplate: "complete-slice",
     toolContract: {
       allowedGsdTools: [
         "gsd_milestone_status",
@@ -293,6 +309,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["validation", "planning"],
+    promptTemplate: "reassess-roadmap",
     toolContract: {
       allowedGsdTools: ["gsd_milestone_status", "gsd_reassess_roadmap"],
       requiredWorkflowTools: ["gsd_milestone_status", "gsd_reassess_roadmap"],
@@ -302,6 +319,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "execute-task",
     phaseChain: ["execution"],
+    promptTemplate: "execute-task",
     toolContract: {
       allowedGsdTools: [
         "gsd_task_complete",
@@ -346,6 +364,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "execute-task",
     phaseChain: ["execution"],
+    promptTemplate: "reactive-execute",
     toolContract: {
       allowedGsdTools: [
         "gsd_milestone_status",
@@ -361,6 +380,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["uat", "completion"],
+    promptTemplate: "run-uat",
     toolContract: {
       allowedGsdTools: [...RUN_UAT_WORKFLOW_TOOL_NAMES, "subagent"],
       requiredWorkflowTools: [...RUN_UAT_WORKFLOW_TOOL_NAMES],
@@ -375,6 +395,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["validation", "planning"],
+    promptTemplate: "gate-evaluate",
     toolContract: {
       allowedGsdTools: ["gsd_save_gate_result"],
       requiredWorkflowTools: ["gsd_save_gate_result"],
@@ -384,6 +405,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["validation", "planning"],
+    promptTemplate: "rewrite-docs",
     toolContract: {
       allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
       requiredWorkflowTools: [],
@@ -408,6 +430,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["discuss", "planning"],
+    promptTemplate: "guided-workflow-preferences",
     toolContract: {
       allowedGsdTools: ["gsd_summary_save"],
       requiredWorkflowTools: [],
@@ -417,6 +440,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["discuss", "planning"],
+    promptTemplate: "guided-discuss-project",
     toolContract: {
       allowedGsdTools: ["gsd_summary_save", "gsd_decision_save", "gsd_requirement_save"],
       requiredWorkflowTools: ["ask_user_questions", "gsd_summary_save"],
@@ -426,6 +450,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["discuss", "planning"],
+    promptTemplate: "guided-discuss-requirements",
     toolContract: {
       allowedGsdTools: ["gsd_requirement_save", "gsd_summary_save"],
       requiredWorkflowTools: ["ask_user_questions", "gsd_requirement_save", "gsd_summary_save"],
@@ -435,6 +460,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["discuss", "planning"],
+    promptTemplate: "guided-research-decision",
     toolContract: {
       allowedGsdTools: ["gsd_summary_save"],
       requiredWorkflowTools: ["ask_user_questions"],
@@ -447,6 +473,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["research"],
+    promptTemplate: "guided-research-project",
     toolContract: {
       allowedGsdTools: [],
       requiredWorkflowTools: [],
@@ -494,3 +521,8 @@ export function getUnitDescriptor(unitType: string): UnitDescriptor | undefined
 export function getUnitPhaseChain(unitType: string): readonly GSDModelPhaseKey[] | null {
   return getUnitDescriptor(unitType)?.phaseChain ?? null;
 }
+
+/** Prompt template id for units with a direct one-template builder. */
+export function getUnitPromptTemplate(unitType: string): string | undefined {
+  return getUnitDescriptor(unitType)?.promptTemplate;
+}

package/src/resources/extensions/gsd/worktree-lifecycle.ts

@@ -21,6 +21,8 @@ import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 
+import type { PreflightResult, PostflightResult } from "./clean-root-preflight.js";
+
 import type { AutoSession } from "./auto/session.js";
 import { debugLog } from "./debug-logger.js";
 import { logWarning } from "./workflow-logger.js";
@@ -153,11 +155,11 @@ export interface WorktreeLifecycleDeps {
   /**
    * Milestone Merge Transaction Module runner.
    *
-   * The field name is preserved for existing test fixtures, but production
-   * wiring now supplies the named transaction wrapper rather than the raw
-   * squash-merge primitive directly.
+   * The field name describes the lifecycle seam; production wiring supplies
+   * the named transaction wrapper rather than the raw legacy
+   * auto-worktree primitive directly.
    */
-  mergeMilestoneToMain: MilestoneMergeTransactionRunner;
+  mergeMilestone: MilestoneMergeTransactionRunner;
 
   // ADR-016 phase 2 / C1 + C2 + C3 + C4 inlined the following fields as
   // direct imports — leaf primitives that did not vary across callers:
@@ -238,7 +240,106 @@ export interface StrandedMilestoneAdoptionOptions {
 
 export type ExitResult =
   | { ok: true; merged: boolean; codeFilesChanged: boolean }
-  | { ok: false; reason: "merge-conflict" | "teardown-failed"; cause?: unknown };
+  | {
+      ok: false;
+      reason:
+        | "merge-conflict"
+        | "teardown-failed"
+        | "preflight-dirty-overlap"
+        | "preflight-unmerged-conflicts"
+        | "merge-failed"
+        | "postflight-stash-restore-failed";
+      cause?: unknown;
+      postflight?: PostflightResult;
+    };
+
+export interface GuardedMilestoneMergeDeps {
+  preflightCleanRoot: (
+    basePath: string,
+    milestoneId: string,
+    notify: NotifyCtx["notify"],
+  ) => PreflightResult;
+  postflightPopStash: (
+    basePath: string,
+    milestoneId: string,
+    stashMarker: string | undefined,
+    notify: NotifyCtx["notify"],
+  ) => PostflightResult;
+}
+
+/**
+ * Optional `exitMilestone(..., { merge: true, guardedMerge })` contract for callers
+ * that need root-clean preflight and postflight stash restoration around the
+ * lifecycle-owned merge attempt. `projectRoot` is the workspace root whose
+ * user changes are protected by the supplied guard functions.
+ */
+export interface GuardedMilestoneMergeOptions extends GuardedMilestoneMergeDeps {
+  projectRoot: string;
+}
+
+type GuardedMilestoneMergeResult = ExitResult;
+
+function preflightBlockedMergeReason(
+  blockedReason: PreflightResult["blockedReason"],
+): Extract<ExitResult, { ok: false }>["reason"] {
+  if (blockedReason?.startsWith("unmerged-conflicts")) {
+    return "preflight-unmerged-conflicts";
+  }
+  return "preflight-dirty-overlap";
+}
+
+/**
+ * Run a milestone merge behind the Worktree Lifecycle seam with the root-clean
+ * stash guard that protects user changes around merge.
+ *
+ * The helper owns the invariant ordering (preflight -> merge callback ->
+ * postflight on every attempted merge path) and returns the same typed result
+ * shape as `exitMilestone`. Auto closeout remains responsible for translating
+ * that result into loop policy (pause vs. stop, visible transcript
+ * preservation, projection rebuild).
+ */
+function runGuardedMilestoneMerge(request: {
+  merge: () => ExitResult;
+  guard: GuardedMilestoneMergeOptions;
+  milestoneId: string;
+  notify: NotifyCtx["notify"];
+}): GuardedMilestoneMergeResult {
+  const { merge, guard, milestoneId, notify } = request;
+  const preflight = guard.preflightCleanRoot(guard.projectRoot, milestoneId, notify);
+  if (preflight.blocked) {
+    return {
+      ok: false,
+      reason: preflightBlockedMergeReason(preflight.blockedReason),
+    };
+  }
+
+  let mergeError: unknown = null;
+  const exitResult = merge();
+  if (!exitResult.ok) {
+    mergeError = exitResult.cause ?? new Error(`exit ${exitResult.reason}`);
+  }
+
+  let postflight: PostflightResult | undefined;
+  if (preflight.stashPushed) {
+    postflight = guard.postflightPopStash(
+      guard.projectRoot,
+      milestoneId,
+      preflight.stashMarker,
+      notify,
+    );
+  }
+
+  if (mergeError instanceof MergeConflictError) {
+    return { ok: false, reason: "merge-conflict", cause: mergeError, postflight };
+  }
+  if (mergeError) {
+    return { ok: false, reason: "merge-failed", cause: mergeError, postflight };
+  }
+  if (postflight?.needsManualRecovery) {
+    return { ok: false, reason: "postflight-stash-restore-failed", postflight };
+  }
+  return exitResult;
+}
 
 /**
  * Session-less merge entry context. Per ADR-016 phase 2 / A1 (#5616), the
@@ -1046,7 +1147,7 @@ function _mergeWorktreeModeImpl(
       };
     }
 
-    const mergeResult = deps.mergeMilestoneToMain(
+    const mergeResult = deps.mergeMilestone(
       originalBasePath,
       milestoneId,
       roadmapResolution.content,
@@ -1213,7 +1314,7 @@ function _mergeBranchModeImpl(
       };
     }
 
-    const mergeResult = deps.mergeMilestoneToMain(
+    const mergeResult = deps.mergeMilestone(
       worktreeBasePath,
       milestoneId,
       roadmapResolution.content,
@@ -1444,18 +1545,41 @@ export class WorktreeLifecycle {
    * With `opts.merge === false`, runs auto-commit and teardown without
    * merging to main.
    *
+   * When `opts.guardedMerge` is present with `opts.merge === true`, the
+   * lifecycle verb also owns the root-clean guard around the merge: preflight
+   * runs before the inner merge, postflight stash restore runs after every
+   * attempted merge path, and guard failures are returned as typed
+   * `ExitResult` reasons.
+   *
    * Returns a typed `ExitResult`. `MergeConflictError` is surfaced as
    * `{ ok: false, reason: "merge-conflict", cause }` instead of thrown,
-   * giving callers a typed branch for the expected failure path.
-   * Unexpected failures (filesystem, git permissions, etc.) are wrapped
-   * as `{ ok: false, reason: "teardown-failed", cause }` so callers always
+   * giving callers a typed branch for the expected failure path. Guarded merge
+   * failures surface as `preflight-dirty-overlap`,
+   * `preflight-unmerged-conflicts`, `merge-failed`, or
+   * `postflight-stash-restore-failed`. Unexpected failures (filesystem, git
+   * permissions, etc.) are wrapped as
+   * `{ ok: false, reason: "teardown-failed", cause }` so callers always
    * receive a discriminated union — no exceptions for any expected outcome.
    */
   exitMilestone(
     milestoneId: string,
-    opts: { merge: boolean; preserveBranch?: boolean; preserveWorktree?: boolean },
+    opts: {
+      merge: boolean;
+      preserveBranch?: boolean;
+      preserveWorktree?: boolean;
+      guardedMerge?: GuardedMilestoneMergeOptions;
+    },
     ctx: NotifyCtx,
   ): ExitResult {
+    if (opts.merge && opts.guardedMerge) {
+      return runGuardedMilestoneMerge({
+        merge: () => this.exitMilestone(milestoneId, { merge: true }, ctx),
+        guard: opts.guardedMerge,
+        milestoneId,
+        notify: ctx.notify,
+      });
+    }
+
     if (opts.merge) {
       try {
         const merged = this._mergeAndExit(milestoneId, ctx);