From a647a2fcb6fe361b4f55c94851d47ad6df713c53 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?T=C3=82CHES?= <afromanguy@me.com>
Date: Wed, 18 Mar 2026 17:22:54 -0600
Subject: [PATCH] refactor: extract dispatchUnit helper, inline dead
 buildDocsCommitInstruction (#1275)

---
 .../extensions/gsd/auto-post-unit.ts          | 57 +++++++++----------
 .../extensions/gsd/guided-flow-queue.ts       |  9 +--
 2 files changed, 28 insertions(+), 38 deletions(-)

diff --git a/src/resources/extensions/gsd/auto-post-unit.ts b/src/resources/extensions/gsd/auto-post-unit.ts
index 2371d13b2..5a4004c90 100644
--- a/src/resources/extensions/gsd/auto-post-unit.ts
+++ b/src/resources/extensions/gsd/auto-post-unit.ts
@@ -64,6 +64,30 @@ import { join } from "node:path";
 /** Throttle STATE.md rebuilds — at most once per 30 seconds */
 const STATE_REBUILD_MIN_INTERVAL_MS = 30_000;
 
+/**
+ * Initialize a unit dispatch: stamp the current time, set `s.currentUnit`,
+ * and persist the initial runtime record. Returns `startedAt` for callers
+ * that need the timestamp.
+ */
+function dispatchUnit(
+  s: AutoSession,
+  basePath: string,
+  unitType: string,
+  unitId: string,
+): number {
+  const startedAt = Date.now();
+  s.currentUnit = { type: unitType, id: unitId, startedAt };
+  writeUnitRuntimeRecord(basePath, unitType, unitId, startedAt, {
+    phase: "dispatched",
+    wrapupWarningSent: false,
+    timeoutAt: null,
+    lastProgressAt: startedAt,
+    progressCount: 0,
+    lastProgressKind: "dispatch",
+  });
+  return startedAt;
+}
+
 export interface PostUnitContext {
   s: AutoSession;
   ctx: ExtensionContext;
@@ -364,19 +388,10 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
   if (s.currentUnit && !s.stepMode) {
     const hookUnit = checkPostUnitHooks(s.currentUnit.type, s.currentUnit.id, s.basePath);
     if (hookUnit) {
-      const hookStartedAt = Date.now();
       if (s.currentUnit) {
         await closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
       }
-      s.currentUnit = { type: hookUnit.unitType, id: hookUnit.unitId, startedAt: hookStartedAt };
-      writeUnitRuntimeRecord(s.basePath, hookUnit.unitType, hookUnit.unitId, hookStartedAt, {
-        phase: "dispatched",
-        wrapupWarningSent: false,
-        timeoutAt: null,
-        lastProgressAt: hookStartedAt,
-        progressCount: 0,
-        lastProgressKind: "dispatch",
-      });
+      dispatchUnit(s, s.basePath, hookUnit.unitType, hookUnit.unitId);
 
       const state = await deriveState(s.basePath);
       updateProgressWidget(ctx, hookUnit.unitType, hookUnit.unitId, state);
@@ -498,16 +513,7 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
 
             const triageUnitType = "triage-captures";
             const triageUnitId = `${mid}/${sid}/triage`;
-            const triageStartedAt = Date.now();
-            s.currentUnit = { type: triageUnitType, id: triageUnitId, startedAt: triageStartedAt };
-            writeUnitRuntimeRecord(s.basePath, triageUnitType, triageUnitId, triageStartedAt, {
-              phase: "dispatched",
-              wrapupWarningSent: false,
-              timeoutAt: null,
-              lastProgressAt: triageStartedAt,
-              progressCount: 0,
-              lastProgressKind: "dispatch",
-            });
+            dispatchUnit(s, s.basePath, triageUnitType, triageUnitId);
             updateProgressWidget(ctx, triageUnitType, triageUnitId, state);
 
             const result = await s.cmdCtx!.newSession();
@@ -568,16 +574,7 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
 
       const qtUnitType = "quick-task";
       const qtUnitId = `${s.currentMilestoneId}/${capture.id}`;
-      const qtStartedAt = Date.now();
-      s.currentUnit = { type: qtUnitType, id: qtUnitId, startedAt: qtStartedAt };
-      writeUnitRuntimeRecord(s.basePath, qtUnitType, qtUnitId, qtStartedAt, {
-        phase: "dispatched",
-        wrapupWarningSent: false,
-        timeoutAt: null,
-        lastProgressAt: qtStartedAt,
-        progressCount: 0,
-        lastProgressKind: "dispatch",
-      });
+      dispatchUnit(s, s.basePath, qtUnitType, qtUnitId);
       const state = await deriveState(s.basePath);
       updateProgressWidget(ctx, qtUnitType, qtUnitId, state);
 
diff --git a/src/resources/extensions/gsd/guided-flow-queue.ts b/src/resources/extensions/gsd/guided-flow-queue.ts
index f8ef7ef30..619690a83 100644
--- a/src/resources/extensions/gsd/guided-flow-queue.ts
+++ b/src/resources/extensions/gsd/guided-flow-queue.ts
@@ -23,13 +23,6 @@ import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { loadQueueOrder, sortByQueueOrder, saveQueueOrder } from "./queue-order.js";
 import { findMilestoneIds, nextMilestoneId } from "./milestone-ids.js";
 
-// ─── Commit Instruction Helper (local copy — avoids circular dep) ───────────
-
-/** Build commit instruction for queue prompts. .gsd/ is managed externally and always gitignored. */
-function buildDocsCommitInstruction(_message: string): string {
-  return "Do not commit planning artifacts — .gsd/ is managed externally.";
-}
-
 // ─── Queue Entry Point ──────────────────────────────────────────────────────
 
 /**
@@ -207,7 +200,7 @@ export async function showQueueAdd(
     preamble,
     existingMilestonesContext: existingContext,
     inlinedTemplates: queueInlinedTemplates,
-    commitInstruction: buildDocsCommitInstruction("docs: queue <milestone list>"),
+    commitInstruction: "Do not commit planning artifacts — .gsd/ is managed externally.",
   });
 
   pi.sendMessage(