gsd-pi 2.81.0 → 2.82.0-dev.2841a1e44

package/src/resources/extensions/gsd/state-reconciliation/spawn-gate.ts

@@ -0,0 +1,60 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 #5707 caller-closure helper. Parent processes that
+// spawn auto-loop workers must reconcile before spawn — otherwise each
+// worker independently detects+repairs the same drift, racing on shared
+// state. This helper centralises the reconcile+catch flow so the two
+// production spawn sites (commands/handlers/parallel.ts and auto/phases.ts
+// startSliceParallel) share one contract.
+
+import {
+  reconcileBeforeDispatch,
+  ReconciliationFailedError,
+  type ReconciliationDeps,
+} from "./index.js";
+
+export type SpawnGateResult =
+  | { ok: true; reason?: string }
+  | { ok: false; reason: string };
+
+export interface SpawnGateDeps extends Partial<ReconciliationDeps> {
+  reconcile?: typeof reconcileBeforeDispatch;
+}
+
+/**
+ * Run reconciliation before spawning workers. Returns ok=true when the run
+ * completed without throwing (blockers ride along but don't fail the gate —
+ * spawn callers can choose how to handle them). On
+ * ReconciliationFailedError, returns ok=false with the error message so the
+ * caller can surface it to the user without re-throwing.
+ *
+ * Other unexpected errors propagate; they are not part of the drift
+ * taxonomy.
+ */
+export async function reconcileBeforeSpawn(
+  basePath: string,
+  deps: SpawnGateDeps = {},
+): Promise<SpawnGateResult> {
+  const reconcileFn = deps.reconcile ?? reconcileBeforeDispatch;
+  try {
+    const result = await reconcileFn(basePath, deps as ReconciliationDeps);
+    if (result.blockers.length > 0) {
+      return {
+        ok: false,
+        reason: `Reconciliation blocker: ${result.blockers[0]}`,
+      };
+    }
+    const repairedKinds = result.repaired.map((d) => d.kind);
+    return {
+      ok: true,
+      reason:
+        repairedKinds.length > 0
+          ? `repaired before spawn: ${repairedKinds.join(", ")}`
+          : undefined,
+    };
+  } catch (err) {
+    if (err instanceof ReconciliationFailedError) {
+      return { ok: false, reason: err.message };
+    }
+    throw err;
+  }
+}

package/src/resources/extensions/gsd/state-reconciliation/types.ts

@@ -0,0 +1,83 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 types for drift-driven state reconciliation.
+
+import type { DeriveStateOptions } from "../state.js";
+import type { GSDState } from "../types.js";
+
+/**
+ * Discriminated union over drift kinds the State Reconciliation Module
+ * recognizes. Each variant carries the identifiers its matching repair needs.
+ */
+export type DriftRecord =
+  | { kind: "stale-sketch-flag"; mid: string; sid: string }
+  | { kind: "unmerged-merge-state"; basePath: string }
+  | { kind: "stale-render"; renderPath: string; reason: string }
+  | { kind: "stale-worker"; lockPath: string; pid: number }
+  | { kind: "unregistered-milestone"; milestoneId: string }
+  | { kind: "roadmap-divergence"; milestoneId: string; sliceId?: string }
+  | {
+      kind: "missing-completion-timestamp";
+      entity: "task" | "slice" | "milestone";
+      ids: string[];
+    };
+
+/**
+ * Context threaded to detector and repair functions. Keeps handlers from
+ * re-deriving state for themselves.
+ */
+export interface DriftContext {
+  basePath: string;
+  state: GSDState;
+}
+
+/**
+ * One drift kind's detect+repair composition.
+ *
+ * Repairs MUST be idempotent: re-running yields the same outcome. This is
+ * load-bearing for the cap=2 lifecycle — the second pass may detect drift
+ * that the first pass already partially repaired.
+ */
+export interface DriftHandler<T extends DriftRecord = DriftRecord> {
+  kind: T["kind"];
+  detect: (state: GSDState, ctx: DriftContext) => T[] | Promise<T[]>;
+  repair: (record: T, ctx: DriftContext) => Promise<void> | void;
+}
+
+/**
+ * Result of a successful reconcileBeforeDispatch call.
+ *
+ * `blockers` are TERMINAL conditions (DB unavailable, slice lock invalid,
+ * dependency cycle) that reconciliation cannot resolve. The caller decides
+ * how to handle them; the orchestrator adapter at auto.ts maps non-empty
+ * blockers to ok=false for the orchestrator's InvariantAdapterResult.
+ *
+ * On repair failure or drift persisting past the cap, reconcileBeforeDispatch
+ * throws ReconciliationFailedError instead of returning.
+ */
+export interface ReconciliationResult {
+  ok: true;
+  stateSnapshot: GSDState;
+  repaired: readonly DriftRecord[];
+  blockers: readonly string[];
+}
+
+/**
+ * Dependencies for reconcileBeforeDispatch. Tests inject fakes for the
+ * registry and state derivation; production callers use defaults.
+ */
+export interface ReconciliationDeps {
+  invalidateStateCache: () => void;
+  deriveState: (
+    basePath: string,
+    opts?: DeriveStateOptions,
+  ) => Promise<GSDState>;
+  /**
+   * Override of the drift handler catalog. Defaults to DRIFT_REGISTRY. Each
+   * handler is parameterized over its own DriftRecord variant; the union of
+   * disjoint parameter types in repair forces the array element type to
+   * DriftHandler<any> here (see registry.ts comment).
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  registry?: ReadonlyArray<DriftHandler<any>>;
+  deriveStateOptions?: DeriveStateOptions;
+}

package/src/resources/extensions/gsd/state-reconciliation.ts

@@ -1,57 +1,25 @@
 // Project/App: GSD-2
-// File Purpose: ADR-015 State Reconciliation module for pre-dispatch runtime invariants.
+// File Purpose: ADR-017 State Reconciliation Module — public entry point.
+// Re-exports the drift-driven implementation from the state-reconciliation/
+// folder so existing import paths (./state-reconciliation.js) keep working.
 
-import { deriveState, invalidateStateCache, type DeriveStateOptions } from "./state.js";
-import type { GSDState } from "./types.js";
+export {
+  reconcileBeforeDispatch,
+  ReconciliationFailedError,
+  DRIFT_REGISTRY,
+} from "./state-reconciliation/index.js";
 
-export type StateReconciliationResult =
-  | {
-      ok: true;
-      stateSnapshot: GSDState;
-      repaired: readonly string[];
-      blockers: readonly string[];
-    }
-  | {
-      ok: false;
-      reason: string;
-      stateSnapshot?: GSDState;
-      repaired: readonly string[];
-      blockers: readonly string[];
-    };
+export type {
+  DriftContext,
+  DriftHandler,
+  DriftRecord,
+  ReconciliationDeps,
+  ReconciliationFailureDetail,
+  ReconciliationResult,
+} from "./state-reconciliation/index.js";
 
-export interface StateReconciliationDeps {
-  invalidateStateCache: () => void;
-  deriveState: (basePath: string, opts?: DeriveStateOptions) => Promise<GSDState>;
-}
-
-const defaultDeps: StateReconciliationDeps = {
-  invalidateStateCache,
-  deriveState,
-};
-
-export async function reconcileBeforeDispatch(
-  basePath: string,
-  deps: StateReconciliationDeps = defaultDeps,
-  opts?: DeriveStateOptions,
-): Promise<StateReconciliationResult> {
-  deps.invalidateStateCache();
-  const stateSnapshot = await deps.deriveState(basePath, opts);
-  const blockers = stateSnapshot.blockers ?? [];
-
-  if (blockers.length > 0 || stateSnapshot.phase === "blocked") {
-    return {
-      ok: false,
-      reason: blockers[0] ?? `State reconciliation blocked in phase ${stateSnapshot.phase}`,
-      stateSnapshot,
-      repaired: ["derive-state-cache-invalidated"],
-      blockers,
-    };
-  }
-
-  return {
-    ok: true,
-    stateSnapshot,
-    repaired: ["derive-state-cache-invalidated"],
-    blockers,
-  };
-}
+export { reconcileBeforeSpawn } from "./state-reconciliation/spawn-gate.js";
+export type {
+  SpawnGateDeps,
+  SpawnGateResult,
+} from "./state-reconciliation/spawn-gate.js";

package/src/resources/extensions/gsd/templates/knowledge.md

@@ -1,7 +1,7 @@
 # Project Knowledge
 
-Append-only register of project-specific rules, patterns, and lessons learned.
-Agents read this before every unit. Add entries when you discover something worth remembering.
+Project-specific rules plus projected patterns and lessons learned.
+Rules are maintained in this file. Patterns and lessons are persisted to the memories table and rendered here on the next session-start projection.
 
 ## Rules
 

package/src/resources/extensions/gsd/tests/artifact-retry-cap.test.ts

@@ -62,7 +62,7 @@ test("#2007 bug 2: recentUnits.push is unconditional — not gated on pendingVer
   );
 });
 
-test("#2007 bug 2: detectStuck is still inside the pendingVerificationRetry guard", () => {
+test("#2007 bug 2: pendingVerificationRetry state is available for dispatch regression coverage", () => {
   const s = new AutoSession();
   s.pendingVerificationRetry = {
     unitId: "M001/S01/T01",

package/src/resources/extensions/gsd/tests/auto-dashboard.test.ts

@@ -14,6 +14,7 @@ import {
   estimateTimeRemaining,
   extractUatSliceId,
   updateProgressWidget,
+  setAutoOutcomeWidget,
   getRoadmapSlicesSync,
   clearSliceProgressCache,
   getWidgetMode,
@@ -220,6 +221,40 @@ test("formatRuntimeHealthSignal surfaces idle recovery instead of generic progre
   });
 });
 
+test("setAutoOutcomeWidget renders a durable next-action handoff", () => {
+  let widgetFactory: any;
+  setAutoOutcomeWidget(
+    {
+      hasUI: true,
+      ui: {
+        setWidget(key: string, factory: any) {
+          if (key === "gsd-outcome") widgetFactory = factory;
+        },
+      },
+    } as any,
+    {
+      status: "paused",
+      title: "Auto-mode paused",
+      detail: "Paused by user request.",
+      unitLabel: "researching M005/S01",
+      nextAction: "Type to steer, or run /gsd auto to resume.",
+      commands: ["/gsd auto", "/gsd status for overview"],
+      startedAt: Date.now() - 2_000,
+    },
+  );
+
+  assert.equal(typeof widgetFactory, "function");
+  const component = widgetFactory(
+    { requestRender() {} },
+    { fg: (_color: string, text: string) => text, bold: (text: string) => text },
+  );
+  const output = component.render(100).join("\n");
+  assert.match(output, /Auto-mode paused/);
+  assert.match(output, /Paused by user request/);
+  assert.match(output, /researching M005\/S01/);
+  assert.match(output, /\/gsd auto/);
+});
+
 test("shouldRenderRoadmapProgress hides pre-roadmap zero-slice progress", () => {
   assert.equal(shouldRenderRoadmapProgress(null), false);
   assert.equal(shouldRenderRoadmapProgress({ done: 0, total: 0, activeSliceTasks: null } as any), false);
@@ -344,6 +379,70 @@ test("updateProgressWidget refreshes slice progress cache immediately", (t) => {
   });
 });
 
+test("updateProgressWidget full mode keeps footer-owned signals out of auto deck", (t) => {
+  const dir = makeTempDir("command-deck");
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+  let widget: { render(width: number): string[]; dispose?: () => void } | null = null;
+
+  t.after(() => {
+    widget?.dispose?.();
+    clearSliceProgressCache();
+    cleanup(dir);
+  });
+
+  updateProgressWidget(
+    {
+      hasUI: true,
+      ui: {
+        setHeader() {},
+        setStatus() {},
+        setWidget(_key: string, factory: any) {
+          if (_key === "gsd-progress") {
+            widget = factory(
+              { requestRender() {} },
+              { fg: (_color: string, text: string) => text, bold: (text: string) => text },
+            );
+          }
+        },
+      },
+      sessionManager: { getSessionId: () => "session-1" },
+    } as any,
+    "execute-task",
+    "M004/S01/T01",
+    {
+      phase: "executing",
+      activeMilestone: { id: "M004", title: "Budget Tracking" },
+      activeSlice: { id: "S01", title: "Schema migration + expense add --repeat" },
+      activeTask: { id: "T01", title: "Add repeat column via idempotent ALTER TABLE" },
+    } as any,
+    {
+      getAutoStartTime: () => Date.now() - 18_000,
+      isStepMode: () => false,
+      getCmdCtx: () => ({
+        model: { id: "claude-sonnet-4-6", provider: "claude-code", contextWindow: 1_000_000 },
+        getContextUsage: () => ({ percent: 0.2, contextWindow: 1_000_000 }),
+        sessionManager: { getEntries: () => [] },
+      } as any),
+      getBasePath: () => dir,
+      isVerbose: () => false,
+      isSessionSwitching: () => false,
+      getCurrentDispatchedModelId: () => "claude-code/claude-sonnet-4-6",
+    },
+  );
+
+  const installedWidget = widget as { render(width: number): string[]; dispose?: () => void } | null;
+  assert.ok(installedWidget, "progress widget should be installed");
+  const rendered = installedWidget.render(120).join("\n");
+
+  assert.match(rendered, /GSD\s+AUTO/);
+  assert.match(rendered, /Budget Tracking/);
+  assert.match(rendered, /T01: Add repeat column via idempotent ALTER TABLE/);
+  assert.match(rendered, /dashboard/);
+  assert.doesNotMatch(rendered, /claude-sonnet-4-6/, "footer owns provider/model display");
+  assert.doesNotMatch(rendered, /0\.2%|ctx|1\.0M/, "footer owns raw context meter display");
+  assert.doesNotMatch(rendered, /\$/, "footer owns session cost display");
+});
+
 test("last commit refresh backs off cleanly when base path is not a git repo", (t) => {
   const dir = makeTempDir("non-git");
   mkdirSync(dir, { recursive: true });