@opengsd/gsd-pi 1.5.0 → 1.6.0

package/src/resources/extensions/gsd/state/derive/from-db.ts

@@ -1,7 +1,7 @@
 // Project/App: gsd-pi
 // File Purpose: DB-backed GSD state derivation pipeline stage.
 
-import type { ActiveRef, GSDState, MilestoneRegistryEntry } from '../../types.js';
+import type { ActiveRef, GSDState, MilestoneRegistryEntry, Phase } from '../../types.js';
 import { join } from 'node:path';
 import { existsSync } from 'node:fs';
 import { isClosedStatus, isDeferredStatus } from '../../status-guards.js';
@@ -41,6 +41,59 @@ import {
 
 const isStatusDone = isClosedStatus;
 
+type MilestoneProgress = { done: number; total: number };
+type SliceProgress = { done: number; total: number };
+type TaskProgress = { done: number; total: number };
+
+interface DerivedStateContext {
+  activeMilestone: ActiveRef | null;
+  activeSlice?: ActiveRef | null;
+  activeTask?: ActiveRef | null;
+  registry: MilestoneRegistryEntry[];
+  requirements: GSDState["requirements"];
+  milestoneProgress: MilestoneProgress;
+  sliceProgress?: SliceProgress;
+  taskProgress?: TaskProgress;
+}
+
+interface DerivedStateOptions {
+  blockers?: string[];
+  lastCompletedMilestone?: ActiveRef | null;
+  includeActiveWorkspace?: boolean;
+}
+
+function buildProgress(context: DerivedStateContext): NonNullable<GSDState["progress"]> {
+  return {
+    milestones: context.milestoneProgress,
+    ...(context.sliceProgress ? { slices: context.sliceProgress } : {}),
+    ...(context.taskProgress ? { tasks: context.taskProgress } : {}),
+  };
+}
+
+function buildDerivedState(
+  context: DerivedStateContext,
+  phase: Phase,
+  nextAction: string,
+  options: DerivedStateOptions = {},
+): GSDState {
+  return {
+    activeMilestone: context.activeMilestone,
+    activeSlice: context.activeSlice ?? null,
+    activeTask: context.activeTask ?? null,
+    phase,
+    recentDecisions: [],
+    blockers: options.blockers ?? [],
+    nextAction,
+    ...(options.lastCompletedMilestone !== undefined
+      ? { lastCompletedMilestone: options.lastCompletedMilestone }
+      : {}),
+    ...(options.includeActiveWorkspace ? { activeWorkspace: undefined } : {}),
+    registry: context.registry,
+    requirements: context.requirements,
+    progress: buildProgress(context),
+  };
+}
+
 function stripMilestonePrefix(title: string): string {
   return title.replace(/^M\d+(?:-[a-z0-9]{6})?[^:]*:\s*/, '') || title;
 }
@@ -182,58 +235,47 @@ function handleNoActiveMilestone(
   const pendingEntries = registry.filter(e => e.status === 'pending');
   const parkedEntries = registry.filter(e => e.status === 'parked');
 
+  const context: DerivedStateContext = {
+    activeMilestone: null,
+    registry,
+    requirements,
+    milestoneProgress,
+  };
+
   if (pendingEntries.length > 0) {
     const blockerDetails = pendingEntries
       .filter(e => e.dependsOn && e.dependsOn.length > 0)
       .map(e => `${e.id} is waiting on unmet deps: ${e.dependsOn!.join(', ')}`);
-    return {
-      activeMilestone: null, activeSlice: null, activeTask: null,
-      phase: 'blocked',
-      recentDecisions: [], blockers: blockerDetails.length > 0
+    return buildDerivedState(context, 'blocked', 'Resolve milestone dependencies before proceeding.', {
+      blockers: blockerDetails.length > 0
         ? blockerDetails
         : ['All remaining milestones are dep-blocked but no deps listed — check CONTEXT.md files'],
-      nextAction: 'Resolve milestone dependencies before proceeding.',
-      registry, requirements,
-      progress: { milestones: milestoneProgress },
-    };
+    });
   }
 
   if (parkedEntries.length > 0) {
     const parkedIds = parkedEntries.map(e => e.id).join(', ');
-    return {
-      activeMilestone: null, activeSlice: null, activeTask: null,
-      phase: 'pre-planning',
-      recentDecisions: [], blockers: [],
-      nextAction: `All remaining milestones are parked (${parkedIds}). Run /gsd unpark <id> or create a new milestone.`,
-      registry, requirements,
-      progress: { milestones: milestoneProgress },
-    };
+    return buildDerivedState(
+      context,
+      'pre-planning',
+      `All remaining milestones are parked (${parkedIds}). Run /gsd unpark <id> or create a new milestone.`,
+    );
   }
 
   if (registry.length === 0) {
-    return {
-      activeMilestone: null, activeSlice: null, activeTask: null,
-      phase: 'pre-planning',
-      recentDecisions: [], blockers: [],
-      nextAction: 'No milestones found. Run /gsd to create one.',
-      registry: [], requirements,
-      progress: { milestones: { done: 0, total: 0 } },
-    };
+    return buildDerivedState(
+      { ...context, registry: [], milestoneProgress: { done: 0, total: 0 } },
+      'pre-planning',
+      'No milestones found. Run /gsd to create one.',
+    );
   }
 
   const lastEntry = registry[registry.length - 1];
   const unmappedActive = countUnmappedActiveRequirements();
   const completionNote = formatCompletePhaseNextAction(unmappedActive);
-  return {
-    activeMilestone: null,
+  return buildDerivedState(context, 'complete', completionNote, {
     lastCompletedMilestone: lastEntry ? { id: lastEntry.id, title: lastEntry.title } : null,
-    activeSlice: null, activeTask: null,
-    phase: 'complete',
-    recentDecisions: [], blockers: [],
-    nextAction: completionNote,
-    registry, requirements,
-    progress: { milestones: milestoneProgress },
-  };
+  });
 }
 
 async function handleAllSlicesDone(
@@ -248,52 +290,48 @@ async function handleAllSlicesDone(
   const verdict = typeof validation?.status === "string" ? validation.status : undefined;
   const validationTerminal = verdict != null && verdict !== "";
 
+  const context: DerivedStateContext = {
+    activeMilestone,
+    registry,
+    requirements,
+    milestoneProgress,
+    sliceProgress,
+  };
+
   if (!validationTerminal) {
-    return {
-      activeMilestone, activeSlice: null, activeTask: null,
-      phase: 'validating-milestone',
-      recentDecisions: [], blockers: [],
-      nextAction: `Validate milestone ${activeMilestone.id} before completion.`,
-      registry, requirements,
-      progress: { milestones: milestoneProgress, slices: sliceProgress },
-    };
+    return buildDerivedState(
+      context,
+      'validating-milestone',
+      `Validate milestone ${activeMilestone.id} before completion.`,
+    );
   }
 
   // All roadmap slices are done (enforced by caller) and verdict is
   // needs-remediation — remediation cannot progress without new slices.
   // Return blocked instead of re-dispatching validate-milestone (#4506).
   if (verdict === 'needs-attention') {
-    return {
-      activeMilestone, activeSlice: null, activeTask: null,
-      phase: 'blocked',
-      recentDecisions: [],
-      blockers: [formatNeedsAttentionBlocker(activeMilestone.id)],
-      nextAction: `Resolve ${activeMilestone.id} validation attention before proceeding.`,
-      registry, requirements,
-      progress: { milestones: milestoneProgress, slices: sliceProgress },
-    };
+    return buildDerivedState(
+      context,
+      'blocked',
+      `Resolve ${activeMilestone.id} validation attention before proceeding.`,
+      { blockers: [formatNeedsAttentionBlocker(activeMilestone.id)] },
+    );
   }
 
   if (verdict === 'needs-remediation') {
-    return {
-      activeMilestone, activeSlice: null, activeTask: null,
-      phase: 'blocked',
-      recentDecisions: [],
-      blockers: [formatNeedsRemediationBlocker(activeMilestone.id)],
-      nextAction: `Resolve ${activeMilestone.id} remediation before proceeding.`,
-      registry, requirements,
-      progress: { milestones: milestoneProgress, slices: sliceProgress },
-    };
+    return buildDerivedState(
+      context,
+      'blocked',
+      `Resolve ${activeMilestone.id} remediation before proceeding.`,
+      { blockers: [formatNeedsRemediationBlocker(activeMilestone.id)] },
+    );
   }
 
-  return {
-    activeMilestone, activeSlice: null, activeTask: null,
-    phase: 'completing-milestone',
-    recentDecisions: [], blockers: [],
-    nextAction: `All slices complete in ${activeMilestone.id}. Write milestone summary.`,
-    registry, requirements,
-    progress: { milestones: milestoneProgress, slices: sliceProgress },
-  };
+  return buildDerivedState(
+    context,
+    'completing-milestone',
+    `All slices complete in ${activeMilestone.id}. Write milestone summary.`,
+  );
 }
 
 function resolveSliceDependencies(activeMilestoneSlices: SliceRow[]): { activeSlice: ActiveRef | null, activeSliceRow: SliceRow | null } {
@@ -356,13 +394,16 @@ export async function deriveStateFromDb(
     : allMilestones;
 
   if (milestones.length === 0) {
-    return {
-      activeMilestone: null, activeSlice: null, activeTask: null,
-      phase: 'pre-planning', recentDecisions: [], blockers: [],
-      nextAction: 'No milestones found. Run /gsd to create one.',
-      registry: [], requirements,
-      progress: { milestones: { done: 0, total: 0 } },
-    };
+    return buildDerivedState(
+      {
+        activeMilestone: null,
+        registry: [],
+        requirements,
+        milestoneProgress: { done: 0, total: 0 },
+      },
+      'pre-planning',
+      'No milestones found. Run /gsd to create one.',
+    );
   }
 
   const { completeMilestoneIds, parkedMilestoneIds } = buildCompletenessSet(basePath, milestones);
@@ -384,12 +425,11 @@ export async function deriveStateFromDb(
     const nextAction = activeMilestoneHasDraft
       ? `Discuss draft context for milestone ${activeMilestone.id}.`
       : `Plan milestone ${activeMilestone.id}.`;
-    return {
-      activeMilestone, activeSlice: null, activeTask: null,
-      phase, recentDecisions: [], blockers: [],
-      nextAction, registry, requirements,
-      progress: { milestones: milestoneProgress },
-    };
+    return buildDerivedState(
+      { activeMilestone, registry, requirements, milestoneProgress },
+      phase,
+      nextAction,
+    );
   }
 
   const allSlicesDone = activeMilestoneSlices.every(s => isStatusDone(s.status));
@@ -397,6 +437,13 @@ export async function deriveStateFromDb(
     done: activeMilestoneSlices.filter(s => isStatusDone(s.status)).length,
     total: activeMilestoneSlices.length,
   };
+  const sliceStateContext: DerivedStateContext = {
+    activeMilestone,
+    registry,
+    requirements,
+    milestoneProgress,
+    sliceProgress,
+  };
 
   if (allSlicesDone) {
     return handleAllSlicesDone(basePath, activeMilestone, registry, requirements, milestoneProgress, sliceProgress);
@@ -407,21 +454,19 @@ export async function deriveStateFromDb(
     // If locked slice wasn't found, it returns null but logs warning, we need to return 'blocked'
     const sliceLock = process.env.GSD_PARALLEL_WORKER ? process.env.GSD_SLICE_LOCK : undefined;
     if (sliceLock) {
-      return {
-        activeMilestone, activeSlice: null, activeTask: null,
-        phase: 'blocked', recentDecisions: [], blockers: [`GSD_SLICE_LOCK=${sliceLock} not found in active milestone slices`],
-        nextAction: 'Slice lock references a non-existent slice — check orchestrator dispatch.',
-        registry, requirements,
-        progress: { milestones: milestoneProgress, slices: sliceProgress },
-      };
+      return buildDerivedState(
+        sliceStateContext,
+        'blocked',
+        'Slice lock references a non-existent slice — check orchestrator dispatch.',
+        { blockers: [`GSD_SLICE_LOCK=${sliceLock} not found in active milestone slices`] },
+      );
     }
-    return {
-      activeMilestone, activeSlice: null, activeTask: null,
-      phase: 'blocked', recentDecisions: [], blockers: ['No slice eligible — check dependency ordering'],
-      nextAction: 'Resolve dependency blockers or plan next slice.',
-      registry, requirements,
-      progress: { milestones: milestoneProgress, slices: sliceProgress },
-    };
+    return buildDerivedState(
+      sliceStateContext,
+      'blocked',
+      'Resolve dependency blockers or plan next slice.',
+      { blockers: ['No slice eligible — check dependency ordering'] },
+    );
   }
   const { activeSlice } = activeSliceContext;
   const activeSliceRow = activeSliceContext.activeSliceRow;
@@ -432,13 +477,11 @@ export async function deriveStateFromDb(
   // PLAN.md and preference flags are projections/configuration and are
   // deliberately not used to infer whether the slice itself is a sketch.
   if (activeSliceRow?.is_sketch === 1) {
-    return {
-      activeMilestone, activeSlice, activeTask: null,
-      phase: 'refining', recentDecisions: [], blockers: [],
-      nextAction: `Refine sketch slice ${activeSlice.id} (${activeSlice.title}) using prior slice context.`,
-      registry, requirements,
-      progress: { milestones: milestoneProgress, slices: sliceProgress },
-    };
+    return buildDerivedState(
+      { ...sliceStateContext, activeSlice },
+      'refining',
+      `Refine sketch slice ${activeSlice.id} (${activeSlice.title}) using prior slice context.`,
+    );
   }
 
   const tasks = getSliceTasks(activeMilestone.id, activeSlice.id);
@@ -447,30 +490,35 @@ export async function deriveStateFromDb(
     done: tasks.filter(t => isStatusDone(t.status)).length,
     total: tasks.length,
   };
+  const taskStateContext: DerivedStateContext = {
+    ...sliceStateContext,
+    activeSlice,
+    taskProgress,
+  };
 
   const activeTaskRow = tasks.find(t => !isStatusDone(t.status));
 
   if (!activeTaskRow && tasks.length > 0) {
-    return {
-      activeMilestone, activeSlice, activeTask: null,
-      phase: 'summarizing', recentDecisions: [], blockers: [],
-      nextAction: `All tasks done in ${activeSlice.id}. Write slice summary and complete slice.`,
-      registry, requirements,
-      progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
-    };
+    return buildDerivedState(
+      taskStateContext,
+      'summarizing',
+      `All tasks done in ${activeSlice.id}. Write slice summary and complete slice.`,
+    );
   }
 
   if (!activeTaskRow) {
-    return {
-      activeMilestone, activeSlice, activeTask: null,
-      phase: 'planning', recentDecisions: [], blockers: [],
-      nextAction: `Slice ${activeSlice.id} has no DB tasks. Plan slice tasks before execution.`,
-      registry, requirements,
-      progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
-    };
+    return buildDerivedState(
+      taskStateContext,
+      'planning',
+      `Slice ${activeSlice.id} has no DB tasks. Plan slice tasks before execution.`,
+    );
   }
 
   const activeTask: ActiveRef = { id: activeTaskRow.id, title: activeTaskRow.title };
+  const activeTaskStateContext: DerivedStateContext = {
+    ...taskStateContext,
+    activeTask,
+  };
 
   // ── Quality gate evaluation check ──────────────────────────────────
   // Pause before execution only when gates owned by the `gate-evaluate`
@@ -485,28 +533,26 @@ export async function deriveStateFromDb(
     "gate-evaluate",
   );
   if (pendingGateCount > 0) {
-    return {
-      activeMilestone, activeSlice, activeTask: null,
-      phase: 'evaluating-gates', recentDecisions: [], blockers: [],
-      nextAction: `Evaluate ${pendingGateCount} quality gate(s) for ${activeSlice.id} before execution.`,
-      registry, requirements,
-      progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
-    };
+    return buildDerivedState(
+      taskStateContext,
+      'evaluating-gates',
+      `Evaluate ${pendingGateCount} quality gate(s) for ${activeSlice.id} before execution.`,
+    );
   }
 
   const blockerTaskId = await detectBlockers(basePath, activeMilestone.id, activeSlice.id, tasks);
   if (blockerTaskId) {
     const replanHistory = getReplanHistory(activeMilestone.id, activeSlice.id);
     if (replanHistory.length === 0) {
-      return {
-        activeMilestone, activeSlice, activeTask,
-        phase: 'replanning-slice', recentDecisions: [],
-        blockers: [`Task ${blockerTaskId} discovered a blocker requiring slice replan`],
-        nextAction: `Task ${blockerTaskId} reported blocker_discovered. Replan slice ${activeSlice.id} before continuing.`,
-        activeWorkspace: undefined,
-        registry, requirements,
-        progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
-      };
+      return buildDerivedState(
+        activeTaskStateContext,
+        'replanning-slice',
+        `Task ${blockerTaskId} reported blocker_discovered. Replan slice ${activeSlice.id} before continuing.`,
+        {
+          blockers: [`Task ${blockerTaskId} discovered a blocker requiring slice replan`],
+          includeActiveWorkspace: true,
+        },
+      );
     }
   }
 
@@ -522,15 +568,15 @@ export async function deriveStateFromDb(
   // and the user's prior resolution never lands.
   const escalatingTaskId = detectPendingEscalation(tasks, basePath);
   if (escalatingTaskId) {
-    return {
-      activeMilestone, activeSlice, activeTask,
-      phase: 'escalating-task', recentDecisions: [],
-      blockers: [`Task ${escalatingTaskId} requires a user decision before the loop can proceed`],
-      nextAction: `Run /gsd escalate show ${escalatingTaskId} to review, then /gsd escalate resolve ${escalatingTaskId} <choice> to proceed.`,
-      activeWorkspace: undefined,
-      registry, requirements,
-      progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
-    };
+    return buildDerivedState(
+      activeTaskStateContext,
+      'escalating-task',
+      `Run /gsd escalate show ${escalatingTaskId} to review, then /gsd escalate resolve ${escalatingTaskId} <choice> to proceed.`,
+      {
+        blockers: [`Task ${escalatingTaskId} requires a user decision before the loop can proceed`],
+        includeActiveWorkspace: true,
+      },
+    );
   }
 
   if (!blockerTaskId) {
@@ -538,24 +584,22 @@ export async function deriveStateFromDb(
     if (isTriggered) {
       const replanHistory = getReplanHistory(activeMilestone.id, activeSlice.id);
       if (replanHistory.length === 0) {
-        return {
-          activeMilestone, activeSlice, activeTask,
-          phase: 'replanning-slice', recentDecisions: [],
-          blockers: ['Triage replan trigger detected — slice replan required'],
-          nextAction: `Triage replan triggered for slice ${activeSlice.id}. Replan before continuing.`,
-          activeWorkspace: undefined,
-          registry, requirements,
-          progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
-        };
+        return buildDerivedState(
+          activeTaskStateContext,
+          'replanning-slice',
+          `Triage replan triggered for slice ${activeSlice.id}. Replan before continuing.`,
+          {
+            blockers: ['Triage replan trigger detected — slice replan required'],
+            includeActiveWorkspace: true,
+          },
+        );
       }
     }
   }
 
-  return {
-    activeMilestone, activeSlice, activeTask,
-    phase: 'executing', recentDecisions: [], blockers: [],
-    nextAction: `Execute ${activeTask.id}: ${activeTask.title} in slice ${activeSlice.id}.`,
-    registry, requirements,
-    progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
-  };
+  return buildDerivedState(
+    activeTaskStateContext,
+    'executing',
+    `Execute ${activeTask.id}: ${activeTask.title} in slice ${activeSlice.id}.`,
+  );
 }

package/src/resources/extensions/gsd/state-reconciliation/drift/artifact-db.ts

@@ -213,21 +213,13 @@ function detectArtifactDbStatusDriftForMilestone(
 
     for (const task of tasks) {
       if (isClosedStatus(task.status)) continue;
-      // Flat-phase: task summaries live in the phase dir as TID-SUMMARY.md
-      let diskTaskSummary = resolveTaskFile(
+      const diskTaskSummary = resolveTaskFile(
         basePath,
         milestoneId,
         slice.id,
         task.id,
         "SUMMARY",
       );
-      if (!diskTaskSummary) {
-        const phaseDir = resolveMilestonePath(basePath, milestoneId);
-        if (phaseDir) {
-          const flatSummary = join(phaseDir, `${task.id}-SUMMARY.md`);
-          if (existsSync(flatSummary)) diskTaskSummary = flatSummary;
-        }
-      }
       if (!diskTaskSummary || !existsSync(diskTaskSummary)) continue;
       addUniqueDrift(drifts, seen, {
         kind: "artifact-db-status-divergence",

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

@@ -20,11 +20,9 @@ import {
 } from "../../gsd-db.js";
 import {
   resolveMilestoneFile,
-  resolveMilestonePath,
   resolveSliceFile,
   resolveTaskFile,
 } from "../../paths.js";
-import { join } from "node:path";
 import type { GSDState } from "../../types.js";
 import type { DriftContext, DriftHandler, DriftRecord } from "../types.js";
 
@@ -105,23 +103,13 @@ function collectMilestoneCompletionDrift(
     for (const task of getSliceTasks(mid, slice.id)) {
       if (!COMPLETE_STATUSES.has(task.status)) continue;
       if (task.completed_at !== null) continue;
-      // Flat-phase: task summaries live in the phase dir as TID-SUMMARY.md.
-      // Legacy: resolveTaskFile returns the tasks/TID/TID-SUMMARY.md path.
-      let taskSummary = resolveTaskFile(
+      const taskSummary = resolveTaskFile(
         ctx.basePath,
         mid,
         slice.id,
         task.id,
         "SUMMARY",
       );
-      // Flat-phase fallback: check the phase dir directly
-      if (!taskSummary) {
-        const phaseDir = resolveMilestonePath(ctx.basePath, mid);
-        if (phaseDir) {
-          const flatSummary = join(phaseDir, `${task.id}-SUMMARY.md`);
-          if (existsSync(flatSummary)) taskSummary = flatSummary;
-        }
-      }
       if (taskSummary && existsSync(taskSummary)) {
         drifts.push({
           kind: "missing-completion-timestamp",
@@ -182,15 +170,7 @@ export function repairMissingCompletionTimestamp(
       task.completed_at !== null ||
       !COMPLETE_STATUSES.has(task.status)
     ) return;
-    // Flat-phase: task summaries live in the phase dir as TID-SUMMARY.md
-    let summary = resolveTaskFile(ctx.basePath, mid, sid, tid, "SUMMARY");
-    if (!summary) {
-      const phaseDir = resolveMilestonePath(ctx.basePath, mid);
-      if (phaseDir) {
-        const flatSummary = join(phaseDir, `${tid}-SUMMARY.md`);
-        if (existsSync(flatSummary)) summary = flatSummary;
-      }
-    }
+    const summary = resolveTaskFile(ctx.basePath, mid, sid, tid, "SUMMARY");
     const ts = summary ? summaryMtimeIso(summary) : null;
     if (!ts) return;
     updateTaskStatus(mid, sid, tid, task.status, ts);

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

@@ -73,6 +73,20 @@ export async function reconcileBeforeDispatch(
   if (!deps.dryRun) {
     const { capturePlanningCompatIfNeeded } = await import("../compat/planning-compat.js");
     await capturePlanningCompatIfNeeded(basePath);
+
+    // Self-heal phantom projection entries (#1257): a renamed/removed phase
+    // directory leaves stale `.compat.json` projection paths that no detector
+    // ever prunes (they all skip missing files), so the marker drifts from disk
+    // reality permanently. Drop entries whose backing file is gone before the
+    // detect passes run. Gated on !dryRun to keep detection read-only.
+    const { pruneOrphanedProjectionEntries } = await import("../compat/compat-marker.js");
+    const prunedCount = pruneOrphanedProjectionEntries(basePath);
+    if (prunedCount > 0) {
+      logWarning(
+        "reconcile",
+        `pruned ${prunedCount} orphaned projection entr${prunedCount === 1 ? "y" : "ies"} from .compat.json (backing file no longer on disk)`,
+      );
+    }
   }
 
   for (let pass = 0; pass < MAX_PASSES; pass++) {