@opengsd/gsd-pi 1.1.1-dev.9bb7453 → 1.1.1-dev.a5a2de8

package/dist/resources/.managed-resources-content-hash

@@ -1 +1 @@
-ba1c57462cf67a0e
+fe5e2f79a21b7d4e

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

@@ -35,6 +35,7 @@ import { probeGitConflictState } from "./git-conflict-state.js";
 import { runTurnGitAction } from "./git-service.js";
 import { parseUnitId } from "./unit-id.js";
 import { resolveExpectedArtifactPath } from "./auto-artifact-paths.js";
+import { checkCloseoutConsistencyGate, formatCloseoutConsistencyBlock, } from "./closeout-consistency-gate.js";
 function resolveExistingExpectedArtifact(unitType, unitId, basePath) {
     const artifactPath = resolveExpectedArtifactPath(unitType, unitId, basePath);
     return artifactPath && existsSync(artifactPath) ? artifactPath : null;
@@ -1355,6 +1356,16 @@ export const DISPATCH_RULES = [
                         prompt: await buildCompleteMilestonePrompt(mid, midTitle, basePath),
                     };
                 }
+                if (milestone) {
+                    const closeoutGate = checkCloseoutConsistencyGate(mid, { refreshFromDisk: true });
+                    if (!closeoutGate.ok) {
+                        return {
+                            action: "stop",
+                            reason: formatCloseoutConsistencyBlock(closeoutGate),
+                            level: "warning",
+                        };
+                    }
+                }
             }
             return {
                 action: "stop",

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

@@ -31,6 +31,7 @@ import { hasBrowserRequiredText } from "./browser-evidence.js";
 import { debugLog } from "./debug-logger.js";
 import { buildSkillActivationBlock, buildSkillDiscoveryVars } from "./skill-activation.js";
 import { findMilestoneIds } from "./milestone-ids.js";
+import { buildRunUatResultPresentation, RUN_UAT_TOOL_PRESENTATION_PLAN_ID } from "./tool-presentation-plan.js";
 export { buildSkillActivationBlock, buildSkillDiscoveryVars };
 // ─── Preamble Cap ─────────────────────────────────────────────────────────────
 /**
@@ -2939,6 +2940,7 @@ export async function buildRunUatPrompt(mid, sliceId, uatPath, uatContent, base)
     emitPromptContextTelemetry("run-uat", contextTelemetry, inlinedContext);
     const uatResultPath = join(base, relSliceFile(base, mid, sliceId, "ASSESSMENT"));
     const uatType = resolveEffectiveUatType(uatContent);
+    const canonicalPresentation = JSON.stringify(buildRunUatResultPresentation(), null, 2);
     return loadPrompt("run-uat", {
         workingDirectory: base,
         milestoneId: mid,
@@ -2946,6 +2948,8 @@ export async function buildRunUatPrompt(mid, sliceId, uatPath, uatContent, base)
         uatPath,
         uatResultPath,
         uatType,
+        toolPresentationPlanId: RUN_UAT_TOOL_PRESENTATION_PLAN_ID,
+        canonicalPresentation,
         inlinedContext,
         skillActivation: buildSkillActivationBlock({
             base,

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

@@ -32,6 +32,7 @@ import { isGsdWorktreePath } from "./worktree-root.js";
 import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
 import { hasImplementationArtifacts } from "./milestone-implementation-evidence.js";
 import { loadAllCaptures, loadPendingCaptures } from "./captures.js";
+import { checkCloseoutConsistencyGate } from "./closeout-consistency-gate.js";
 // Re-export so existing consumers of auto-recovery.ts keep working.
 export { resolveExpectedArtifactPath, diagnoseExpectedArtifact };
 export { classifyMilestoneSummaryContent, } from "./milestone-summary-classifier.js";
@@ -571,10 +572,8 @@ export function verifyExpectedArtifact(unitType, unitId, base) {
             return false;
         const { milestone: mid } = parseUnitId(unitId);
         if (mid && isDbAvailable()) {
-            const dbMilestone = getMilestone(mid);
-            if (!dbMilestone)
-                return false;
-            if (!isClosedStatus(dbMilestone.status) && summaryOutcome !== "success")
+            const closeoutGate = checkCloseoutConsistencyGate(mid, { refreshFromDisk: true });
+            if (!closeoutGate.ok)
                 return false;
         }
         if (hasImplementationArtifacts(base, mid) === "absent")

package/dist/resources/extensions/gsd/auto-unit-tool-scope.js

@@ -1,57 +1,6 @@
 import { parseUnitId } from "./unit-id.js";
-import { RUN_UAT_WORKFLOW_TOOL_NAMES } from "./tool-presentation-plan.js";
-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",
-];
-export const AUTO_UNIT_SCOPED_TOOLS = {
-    "research-milestone": ["gsd_summary_save", "gsd_decision_save"],
-    "plan-milestone": ["gsd_plan_milestone", "gsd_decision_save", "gsd_requirement_update"],
-    "discuss-milestone": [
-        "gsd_summary_save",
-        "gsd_decision_save",
-        "gsd_requirement_save",
-        "gsd_requirement_update",
-        "gsd_plan_milestone",
-        "gsd_milestone_generate_id",
-    ],
-    "discuss-slice": ["gsd_summary_save", "gsd_decision_save"],
-    "validate-milestone": ["gsd_validate_milestone", "gsd_reassess_roadmap", "subagent"],
-    "complete-milestone": ["gsd_complete_milestone", "subagent"],
-    "research-slice": ["gsd_summary_save", "gsd_decision_save"],
-    "plan-slice": ["gsd_plan_slice", "gsd_plan_task", "gsd_decision_save"],
-    "refine-slice": ["gsd_plan_slice", "gsd_plan_task", "gsd_decision_save"],
-    "replan-slice": ["gsd_replan_slice", "gsd_plan_task", "gsd_decision_save"],
-    "complete-slice": ["gsd_slice_complete", "gsd_task_reopen", "gsd_replan_slice", "gsd_decision_save", "gsd_requirement_update", "subagent"],
-    "reassess-roadmap": ["gsd_reassess_roadmap"],
-    "execute-task": ["gsd_task_complete", "gsd_decision_save"],
-    "execute-task-simple": ["gsd_task_complete", "gsd_decision_save"],
-    "reactive-execute": ["gsd_task_complete", "gsd_decision_save"],
-    "run-uat": [...RUN_UAT_WORKFLOW_TOOL_NAMES, "subagent", ...RUN_UAT_BROWSER_TOOL_NAMES],
-    "gate-evaluate": ["gsd_save_gate_result"],
-    "rewrite-docs": ["gsd_summary_save", "gsd_decision_save"],
-    "workflow-preferences": ["gsd_summary_save"],
-    "discuss-project": ["gsd_summary_save", "gsd_decision_save", "gsd_requirement_save"],
-    "discuss-requirements": ["gsd_requirement_save", "gsd_summary_save"],
-    "research-decision": ["gsd_summary_save"],
-    "research-project": ["gsd_summary_save", "gsd_decision_save"],
-};
+import { AUTO_UNIT_SCOPED_TOOLS, getForbiddenGsdToolReason, } from "./unit-tool-contracts.js";
+export { AUTO_UNIT_SCOPED_TOOLS, RUN_UAT_BROWSER_TOOL_NAMES, } from "./unit-tool-contracts.js";
 const WORKFLOW_TOOL_ALIASES = {
     gsd_save_decision: "gsd_decision_save",
     gsd_update_requirement: "gsd_requirement_update",
@@ -88,6 +37,7 @@ const SCOPED_GSD_LIFECYCLE_TOOLS = new Set([
 ]
     .filter((tool) => tool.startsWith("gsd_"))
     .map(canonicalWorkflowToolName));
+export const GSD_PHASE_SCOPE_DISPLAY_REASON = "This GSD phase only allows its scoped workflow tools.";
 function stripMcpToolPrefix(toolName) {
     if (!toolName.startsWith("mcp__"))
         return toolName;
@@ -103,11 +53,18 @@ export function isWorkflowAliasTool(toolName) {
 }
 function hardBlockReason(unitType, what) {
     return [
-        `HARD BLOCK: unit "${unitType}" is constrained by auto-unit tool scope — ${what}.`,
+        `HARD BLOCK: Tool Contract failure for unit "${unitType}" — ${what}.`,
         "This is a mechanical phase-boundary gate. You MUST NOT proceed, retry the same call,",
         "or route around this block; the orchestrator owns phase transitions.",
     ].join(" ");
 }
+function hardBlock(unitType, what) {
+    return {
+        block: true,
+        reason: hardBlockReason(unitType, what),
+        displayReason: GSD_PHASE_SCOPE_DISPLAY_REASON,
+    };
+}
 function allowedGsdToolsForUnit(unitType) {
     return [...new Set((AUTO_UNIT_SCOPED_TOOLS[unitType] ?? [])
             .filter((tool) => tool.startsWith("gsd_"))
@@ -143,20 +100,14 @@ function shouldBlockTaskCompletionScope(unitType, unitId, toolName, input) {
         actualTask === expected.task) {
         return { block: false };
     }
-    return {
-        block: true,
-        reason: hardBlockReason(unitType, `gsd_task_complete may only complete the active task ${expected.milestone}/${expected.slice}/${expected.task}; requested ${actualMilestone}/${actualSlice}/${actualTask}`),
-    };
+    return hardBlock(unitType, `gsd_task_complete may only complete the active task ${expected.milestone}/${expected.slice}/${expected.task}; requested ${actualMilestone}/${actualSlice}/${actualTask}`);
 }
 export function shouldBlockAutoUnitToolCall(unitType, toolName, input, unitId) {
     const scopedTools = AUTO_UNIT_SCOPED_TOOLS[unitType];
     if (!scopedTools)
         return { block: false };
     if (isNativeWorkflowTool(toolName)) {
-        return {
-            block: true,
-            reason: hardBlockReason(unitType, "native Workflow is not permitted inside a dispatched GSD auto-mode unit"),
-        };
+        return hardBlock(unitType, "native Workflow is not permitted inside a dispatched GSD auto-mode unit");
     }
     const taskScope = shouldBlockTaskCompletionScope(unitType, unitId, toolName, input);
     if (taskScope.block)
@@ -167,8 +118,9 @@ export function shouldBlockAutoUnitToolCall(unitType, toolName, input, unitId) {
     const allowedTools = allowedGsdToolsForUnit(unitType);
     if (allowedTools.includes(canonicalTool))
         return { block: false };
-    return {
-        block: true,
-        reason: hardBlockReason(unitType, `GSD lifecycle tool "${canonicalTool}" is not permitted; allowed GSD tools: ${allowedTools.length > 0 ? allowedTools.join(", ") : "(none)"}`),
-    };
+    const forbiddenReason = getForbiddenGsdToolReason(unitType, canonicalTool);
+    if (forbiddenReason) {
+        return hardBlock(unitType, `GSD lifecycle tool "${canonicalTool}" is not permitted; ${forbiddenReason} Fix unit-tool-contracts.ts or the ${unitType} prompt.`);
+    }
+    return hardBlock(unitType, `GSD lifecycle tool "${canonicalTool}" is not permitted; allowed GSD tools: ${allowedTools.length > 0 ? allowedTools.join(", ") : "(none)"}`);
 }

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

@@ -26,6 +26,7 @@ import { MILESTONE_ID_RE } from "./milestone-ids.js";
 import { runWorktreePostCreateHook } from "./worktree-post-create-hook.js";
 import { classifyProject } from "./detection.js";
 import { nativeGetCurrentBranch, nativeDetectMainBranch, nativeWorkingTreeStatus, nativeAddAllWithExclusions, nativeCommit, nativeCheckoutBranch, nativeMergeSquash, nativeConflictFiles, nativeAddPaths, nativeRmForce, nativeBranchDelete, nativeBranchForceReset, nativeBranchExists, nativeDiffNumstat, nativeUpdateRef, nativeIsAncestor, nativeMergeAbort, nativeWorktreeList, nativeLsFiles, } from "./native-git-bridge.js";
+import { CLOSEOUT_CONSISTENCY_BLOCKED_REASON, checkCloseoutConsistencyGate, formatCloseoutConsistencyBlock, } from "./closeout-consistency-gate.js";
 import { gsdHome } from "./gsd-home.js";
 import { createWorkspace } from "./workspace.js";
 import { _finalizeProjectionForMergeImpl, _projectRootToWorktreeImpl, _projectWorktreeToRootImpl, } from "./worktree-state-projection.js";
@@ -1513,17 +1514,29 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
     // symlink layout) — ATTACHing a WAL-mode file to itself corrupts the
     // database (#2823).
     if (isDbAvailable()) {
+        const contract = resolveGsdPathContract(worktreeCwd, originalBasePath_);
+        const worktreeDbPath = join(contract.worktreeGsd ?? join(worktreeCwd, ".gsd"), "gsd.db");
+        const mainDbPath = contract.projectDb;
         try {
-            const contract = resolveGsdPathContract(worktreeCwd, originalBasePath_);
-            const worktreeDbPath = join(contract.worktreeGsd ?? join(worktreeCwd, ".gsd"), "gsd.db");
-            const mainDbPath = contract.projectDb;
+            const activeDbPath = getDbPath();
+            if (activeDbPath && _shouldReconcileWorktreeDb(activeDbPath, mainDbPath)) {
+                closeDatabase();
+                if (!openDatabase(mainDbPath)) {
+                    throw new Error(`cannot open project DB at ${mainDbPath}`);
+                }
+            }
             if (_shouldReconcileWorktreeDb(worktreeDbPath, mainDbPath)) {
                 reconcileWorktreeDb(mainDbPath, worktreeDbPath);
             }
         }
         catch (err) {
-            /* non-fatal */
-            logError("worktree", `DB reconciliation failed: ${err instanceof Error ? err.message : String(err)}`);
+            const message = `DB reconciliation failed before milestone ${milestoneId} merge: ${err instanceof Error ? err.message : String(err)}`;
+            logError("worktree", message);
+            throw new GSDError(GSD_GIT_ERROR, `${message}. Recovery reason: ${CLOSEOUT_CONSISTENCY_BLOCKED_REASON}.`);
+        }
+        const closeoutGate = checkCloseoutConsistencyGate(milestoneId);
+        if (!closeoutGate.ok) {
+            throw new GSDError(GSD_GIT_ERROR, formatCloseoutConsistencyBlock(closeoutGate));
         }
     }
     // 2. Get completed slices for commit message

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

@@ -65,6 +65,9 @@ function readDetails(result) {
 }
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- result shape varies by tool
 function formatToolErrorText(result, details) {
+    if (typeof details?.displayReason === "string" && details.displayReason) {
+        return details.displayReason;
+    }
     const message = details?.error
         ?? result?.content?.find((entry) => entry.type === "text")?.text
         ?? "unknown";
@@ -405,6 +408,9 @@ export function registerDbTools(pi) {
         kind: StringEnum(["gsd_uat_exec", "gsd_exec", "screenshot", "log", "url", "browser"], { description: "Evidence kind" }),
         ref: Type.String({ description: "Evidence ID, approved .gsd path, or URL" }),
         note: Type.Optional(Type.String({ description: "Short evidence note" })),
+        unitType: Type.Optional(Type.String({ description: "Unit that produced the evidence" })),
+        tool: Type.Optional(Type.String({ description: "Tool that produced the evidence" })),
+        executionId: Type.Optional(Type.String({ description: "Stable execution or artifact id" })),
     });
     const uatCheck = Type.Object({
         id: Type.String({ description: "Stable check ID from the UAT spec" }),
@@ -416,17 +422,17 @@ export function registerDbTools(pi) {
         nonAutomatable: Type.Optional(Type.Boolean({ description: "True when the check is explicitly non-automatable" })),
     });
     const toolPresentationBlock = Type.Object({
-        surface: StringEnum(["provider-tools", "claude-code-sdk", "mcp", "hybrid"], { description: "Tool presentation surface" }),
+        surface: Type.Optional(StringEnum(["provider-tools", "claude-code-sdk", "mcp", "hybrid"], { description: "Tool presentation surface" })),
         model: Type.Optional(Type.Object({
             provider: Type.Optional(Type.String()),
             api: Type.Optional(Type.String()),
             id: Type.Optional(Type.String()),
         })),
-        presentedTools: Type.Array(Type.String(), { description: "Tool names actually presented to the model" }),
-        blockedTools: Type.Array(Type.Object({
+        presentedTools: Type.Optional(Type.Array(Type.String(), { description: "Tool names actually presented to the model" })),
+        blockedTools: Type.Optional(Type.Array(Type.Object({
             name: Type.String(),
             reason: Type.String(),
-        }), { description: "Tool names blocked from the model with reasons" }),
+        }), { description: "Tool names blocked from the model with reasons" })),
         aliases: Type.Optional(Type.Array(Type.Object({
             requested: Type.String(),
             canonical: Type.String(),
@@ -448,12 +454,12 @@ export function registerDbTools(pi) {
             "Do not use raw gsd_summary_save as a substitute for UAT results.",
         ],
         parameters: Type.Object({
-            milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }),
-            sliceId: Type.String({ description: "Slice ID (e.g. S01)" }),
-            uatType: StringEnum(["artifact-driven", "browser-executable", "runtime-executable", "live-runtime", "mixed", "human-experience"], { description: "Declared UAT mode" }),
-            verdict: StringEnum(["PASS", "FAIL", "PARTIAL"], { description: "Overall UAT verdict" }),
-            checks: Type.Array(uatCheck, { description: "Structured check results" }),
-            presentation: toolPresentationBlock,
+            milestoneId: Type.Optional(Type.String({ description: "Milestone ID (e.g. M001)" })),
+            sliceId: Type.Optional(Type.String({ description: "Slice ID (e.g. S01)" })),
+            uatType: Type.Optional(Type.String({ description: "Declared UAT mode" })),
+            verdict: Type.Optional(Type.String({ description: "Overall UAT verdict: PASS, FAIL, or PARTIAL" })),
+            checks: Type.Optional(Type.Array(uatCheck, { description: "Structured check results" })),
+            presentation: Type.Optional(toolPresentationBlock),
             notes: Type.Optional(Type.String({ description: "Overall verdict rationale" })),
             attempt: Type.Optional(Type.String({ description: "Attempt number or auto" })),
             previousAttemptId: Type.Optional(Type.String({ description: "Prior attempt ID, when retrying" })),

package/dist/resources/extensions/gsd/bootstrap/register-hooks.js

@@ -30,7 +30,7 @@ import { getGuidedUnitContext } from "../guided-unit-context.js";
 import { registerPlanMilestoneSchemaRecovery } from "./plan-milestone-schema-recovery.js";
 import { AUTO_UNIT_SCOPED_TOOLS, RUN_UAT_BROWSER_TOOL_NAMES, isWorkflowAliasTool } from "../auto-unit-tool-scope.js";
 import { filterToolsForProvider } from "../model-router.js";
-import { RUN_UAT_WORKFLOW_TOOL_NAMES } from "../tool-presentation-plan.js";
+import { RUN_UAT_READ_ONLY_TOOL_NAMES, RUN_UAT_WORKFLOW_TOOL_NAMES } from "../tool-presentation-plan.js";
 let approvalQuestionAbortInFlight = false;
 async function loadWelcomeScreenModule() {
     const candidates = [];
@@ -204,7 +204,12 @@ export function buildMinimalAutoGsdToolSet(activeToolNames, unitType, registered
     return withPreservedShimTools([...new Set([...preserved, ...scoped])]);
 }
 export function buildRunUatGsdToolSet(activeToolNames, registeredToolNames = activeToolNames) {
-    const scoped = resolveScopedToolNames([...activeToolNames, ...registeredToolNames], [...RUN_UAT_WORKFLOW_TOOL_NAMES, "subagent", ...RUN_UAT_BROWSER_TOOL_NAMES]);
+    const scoped = resolveScopedToolNames([...activeToolNames, ...registeredToolNames], [
+        ...RUN_UAT_WORKFLOW_TOOL_NAMES,
+        ...RUN_UAT_READ_ONLY_TOOL_NAMES,
+        "subagent",
+        ...RUN_UAT_BROWSER_TOOL_NAMES,
+    ]);
     return [...new Set(scoped)];
 }
 export function buildMinimalGsdWorkflowToolSet(activeToolNames, registeredToolNames = activeToolNames) {
@@ -382,6 +387,11 @@ function isContextDraftSummarySave(toolName, input) {
         return false;
     return input.artifact_type === "CONTEXT-DRAFT";
 }
+function withDepthGateDisplayReason(result, displayReason = "Depth confirmation is waiting for your answer.") {
+    if (!result.block)
+        return result;
+    return { ...result, displayReason };
+}
 function shouldBlockDeferredApprovalTool(toolName, input, basePath) {
     if (deferredApprovalGate?.basePath !== basePath)
         return { block: false };
@@ -389,14 +399,14 @@ function shouldBlockDeferredApprovalTool(toolName, input, basePath) {
         return { block: false };
     if (isContextDraftSummarySave(toolName, input))
         return { block: false };
-    return {
+    return withDepthGateDisplayReason({
         block: true,
         reason: [
             `HARD BLOCK: Approval question "${deferredApprovalGate.gateId}" has been shown to the user.`,
             `Only CONTEXT-DRAFT persistence may finish in this same assistant turn.`,
             `Wait for the user's answer before calling additional tools.`,
         ].join(" "),
-    };
+    });
 }
 export function resolveNotificationStoreBasePath(basePath) {
     return resolveWorktreeProjectRoot(basePath);
@@ -754,7 +764,7 @@ export function registerHooks(pi, ecosystemHandlers) {
                     if (ctx) {
                         await maybePauseAutoForApprovalGate(ctx, pi, true, "Depth confirmation is waiting for your answer — pausing auto-mode.");
                     }
-                    return bashGuard;
+                    return withDepthGateDisplayReason(bashGuard);
                 }
             }
             else {
@@ -763,7 +773,7 @@ export function registerHooks(pi, ecosystemHandlers) {
                     if (ctx) {
                         await maybePauseAutoForApprovalGate(ctx, pi, true, "Depth confirmation is waiting for your answer — pausing auto-mode.");
                     }
-                    return gateGuard;
+                    return withDepthGateDisplayReason(gateGuard);
                 }
             }
         }
@@ -847,8 +857,9 @@ export function registerHooks(pi, ecosystemHandlers) {
         if (!isToolCallEventType("write", event))
             return;
         const result = shouldBlockContextWrite(event.toolName, event.input.path, await getDiscussionMilestoneIdFor(discussionBasePath), isQueuePhaseActive(discussionBasePath), discussionBasePath);
-        if (result.block)
-            return result;
+        if (result.block) {
+            return withDepthGateDisplayReason(result, "Depth check required before writing milestone context.");
+        }
     });
     // ── Safety harness: evidence collection + destructive command blocking ──
     pi.on("tool_call", async (event, ctx) => {

package/dist/resources/extensions/gsd/bootstrap/write-gate.js

@@ -2,7 +2,7 @@
 import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { minimatch } from "minimatch";
-import { shouldBlockAutoUnitToolCall } from "../auto-unit-tool-scope.js";
+import { GSD_PHASE_SCOPE_DISPLAY_REASON, shouldBlockAutoUnitToolCall } from "../auto-unit-tool-scope.js";
 import { getIsolationMode } from "../preferences.js";
 import { compileSubagentPermissionContract } from "../unit-context-manifest.js";
 import { logWarning } from "../workflow-logger.js";
@@ -643,6 +643,13 @@ function blockReason(unitType, mode, what) {
         `the work belongs in execute-task, not in a planning unit.`,
     ].join(" ");
 }
+function planningBlock(unitType, mode, what) {
+    return {
+        block: true,
+        reason: blockReason(unitType, mode, what),
+        displayReason: GSD_PHASE_SCOPE_DISPLAY_REASON,
+    };
+}
 /**
  * Planning-unit tool-policy enforcement. Returns { block } per the policy
  * resolved from the active unit's manifest:
@@ -690,10 +697,10 @@ export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitT
         if (tool.startsWith("gsd_"))
             return { block: false };
         if (PLANNING_WRITE_TOOLS.has(tool) || tool === "bash" || PLANNING_SUBAGENT_TOOLS.has(tool)) {
-            return { block: true, reason: blockReason(unitType, policy.mode, `${tool} is not permitted (read-only)`) };
+            return planningBlock(unitType, policy.mode, `${tool} is not permitted (read-only)`);
         }
         // Unknown tool in read-only mode — block by default.
-        return { block: true, reason: blockReason(unitType, policy.mode, `tool "${tool}" is not on the read-only allowlist`) };
+        return planningBlock(unitType, policy.mode, `tool "${tool}" is not on the read-only allowlist`);
     }
     // planning / planning-dispatch / docs / verification modes share the same surface for safe tools, bash, and subagent.
     if (PLANNING_SAFE_TOOLS.has(tool))
@@ -711,10 +718,7 @@ export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitT
             // instead of silently bypassing the gate.
             if (agentClasses === undefined) {
                 warnMissingControlledDispatchAgentClasses(unitType, policy.mode, tool);
-                return {
-                    block: true,
-                    reason: blockReason(unitType, policy.mode, `subagent dispatch blocked: stale caller did not supply agent identities for "${tool}"; update extractSubagentAgentClasses to handle this input shape`),
-                };
+                return planningBlock(unitType, policy.mode, `subagent dispatch blocked: stale caller did not supply agent identities for "${tool}"; update extractSubagentAgentClasses to handle this input shape`);
             }
             // agentClasses was explicitly provided but resolved to an empty list (for
             // example, a bare tool call with no agent field). Pass through; no agents
@@ -724,41 +728,29 @@ export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitT
             }
             const globallyDisallowed = requested.find(a => !isReadOnlySpecialist(a));
             if (globallyDisallowed) {
-                return {
-                    block: true,
-                    reason: blockReason(unitType, policy.mode, `subagent dispatch of "${globallyDisallowed}" not permitted; only read-only specialists (${allowedPlanningDispatchAgentsList()}) may be dispatched from ${policy.mode} units`),
-                };
+                return planningBlock(unitType, policy.mode, `subagent dispatch of "${globallyDisallowed}" not permitted; only read-only specialists (${allowedPlanningDispatchAgentsList()}) may be dispatched from ${policy.mode} units`);
             }
             const disallowedByPolicy = requested.find(a => !allowed.has(a));
             if (disallowedByPolicy) {
-                return {
-                    block: true,
-                    reason: blockReason(unitType, policy.mode, `subagent dispatch of "${disallowedByPolicy}" not permitted by ToolsPolicy.allowedSubagents; permitted agents for this unit: ${allowedSubagents.join(", ")}`),
-                };
+                return planningBlock(unitType, policy.mode, `subagent dispatch of "${disallowedByPolicy}" not permitted by ToolsPolicy.allowedSubagents; permitted agents for this unit: ${allowedSubagents.join(", ")}`);
             }
             return { block: false };
         }
-        return { block: true, reason: blockReason(unitType, policy.mode, `subagent dispatch is not permitted in planning units`) };
+        return planningBlock(unitType, policy.mode, "subagent dispatch is not permitted in planning units");
     }
     if (tool === "bash") {
         if (policy.mode === "verification") {
             if (BASH_VERIFICATION_RE.test(pathOrCommand) || BASH_READ_ONLY_RE.test(pathOrCommand))
                 return { block: false };
-            return {
-                block: true,
-                reason: blockReason(unitType, policy.mode, `bash is restricted to build/test verification commands (npm run build, npm test, etc.); cannot run "${pathOrCommand.slice(0, 80)}${pathOrCommand.length > 80 ? "…" : ""}"`),
-            };
+            return planningBlock(unitType, policy.mode, `bash is restricted to build/test verification commands (npm run build, npm test, etc.); cannot run "${pathOrCommand.slice(0, 80)}${pathOrCommand.length > 80 ? "…" : ""}"`);
         }
         if (BASH_READ_ONLY_RE.test(pathOrCommand))
             return { block: false };
-        return {
-            block: true,
-            reason: blockReason(unitType, policy.mode, `bash is restricted to read-only commands (cat/grep/git log/etc); cannot run "${pathOrCommand.slice(0, 80)}${pathOrCommand.length > 80 ? "…" : ""}"`),
-        };
+        return planningBlock(unitType, policy.mode, `bash is restricted to read-only commands (cat/grep/git log/etc); cannot run "${pathOrCommand.slice(0, 80)}${pathOrCommand.length > 80 ? "…" : ""}"`);
     }
     if (PLANNING_WRITE_TOOLS.has(tool)) {
         if (!pathOrCommand) {
-            return { block: true, reason: blockReason(unitType, policy.mode, `${tool} called with empty path`) };
+            return planningBlock(unitType, policy.mode, `${tool} called with empty path`);
         }
         const absPath = isAbsolute(pathOrCommand) ? pathOrCommand : resolve(basePath, pathOrCommand);
         // Always allow .gsd/ writes — that's where planning artifacts live.
@@ -768,10 +760,7 @@ export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitT
         if (policy.mode === "docs" && matchesAllowedGlob(absPath, basePath, policy.allowedPathGlobs)) {
             return { block: false };
         }
-        return {
-            block: true,
-            reason: blockReason(unitType, policy.mode, `cannot ${tool} "${pathOrCommand}" — writes are restricted to .gsd/${policy.mode === "docs" ? " and " + policy.allowedPathGlobs.join(", ") : ""}`),
-        };
+        return planningBlock(unitType, policy.mode, `cannot ${tool} "${pathOrCommand}" — writes are restricted to .gsd/${policy.mode === "docs" ? " and " + policy.allowedPathGlobs.join(", ") : ""}`);
     }
     // Unknown tool name — pass through. Other layers (queue, pending-gate,
     // CONTEXT.md write) catch known mutating shapes; defaulting to allow here

package/dist/resources/extensions/gsd/closeout-consistency-gate.js

@@ -0,0 +1,61 @@
+// Project/App: gsd-pi
+// File Purpose: Shared DB-backed guard for milestone closeout finalization.
+import { getDbPath, getLatestAssessmentByScope, getMilestone, getMilestoneSlices, getPendingGates, getSliceTasks, isDbAvailable, refreshOpenDatabaseFromDisk, } from "./gsd-db.js";
+import { isClosedStatus } from "./status-guards.js";
+export const CLOSEOUT_CONSISTENCY_BLOCKED_REASON = "closeout-consistency-blocked";
+function blocked(reason, message) {
+    return {
+        ok: false,
+        reason,
+        recoveryReason: CLOSEOUT_CONSISTENCY_BLOCKED_REASON,
+        message,
+    };
+}
+function isFileBackedDbPath(path) {
+    return Boolean(path && path !== ":memory:");
+}
+export function checkCloseoutConsistencyGate(milestoneId, options = {}) {
+    if (!isDbAvailable()) {
+        return blocked("db-unavailable", `Closeout consistency blocked for ${milestoneId}: canonical DB is unavailable.`);
+    }
+    if (options.refreshFromDisk && isFileBackedDbPath(getDbPath()) && !refreshOpenDatabaseFromDisk()) {
+        return blocked("db-refresh-failed", `Closeout consistency blocked for ${milestoneId}: canonical DB refresh failed.`);
+    }
+    const milestone = getMilestone(milestoneId);
+    if (!milestone) {
+        return blocked("milestone-missing", `Closeout consistency blocked for ${milestoneId}: milestone is missing from canonical DB.`);
+    }
+    if (!isClosedStatus(milestone.status)) {
+        return blocked("milestone-open", `Closeout consistency blocked for ${milestoneId}: canonical DB milestone status is "${milestone.status}".`);
+    }
+    if (milestone.status !== "skipped") {
+        const validation = getLatestAssessmentByScope(milestoneId, "milestone-validation");
+        if (validation?.status !== "pass") {
+            return blocked("validation-not-pass", `Closeout consistency blocked for ${milestoneId}: latest milestone validation is "${validation?.status ?? "absent"}".`);
+        }
+    }
+    const slices = getMilestoneSlices(milestoneId);
+    if (slices.length === 0 && milestone.status !== "skipped") {
+        return blocked("slice-missing", `Closeout consistency blocked for ${milestoneId}: no slices exist in canonical DB.`);
+    }
+    for (const slice of slices) {
+        if (!isClosedStatus(slice.status)) {
+            return blocked("slice-open", `Closeout consistency blocked for ${milestoneId}: slice ${slice.id} status is "${slice.status}".`);
+        }
+        for (const task of getSliceTasks(milestoneId, slice.id)) {
+            if (!isClosedStatus(task.status)) {
+                return blocked("task-open", `Closeout consistency blocked for ${milestoneId}: task ${slice.id}/${task.id} status is "${task.status}".`);
+            }
+        }
+        const pendingGate = getPendingGates(milestoneId, slice.id)[0];
+        if (pendingGate) {
+            return blocked("quality-gate-pending", `Closeout consistency blocked for ${milestoneId}: quality gate ${pendingGate.gate_id} is still pending for ${slice.id}.`);
+        }
+    }
+    return { ok: true };
+}
+export function formatCloseoutConsistencyBlock(result) {
+    if (result.ok)
+        return "";
+    return `${result.message} Recovery reason: ${result.recoveryReason}. Resolve the canonical DB state and run /gsd auto to retry.`;
+}