@opengsd/gsd-pi 1.1.1-dev.b2556262 → 1.2.0-dev.0b870afa

package/src/resources/extensions/gsd/milestone-readiness.ts

@@ -0,0 +1,125 @@
+// Project/App: gsd-pi
+// File Purpose: Classify milestone readiness from DB status, slices, and artifacts.
+
+import { readFileSync } from "node:fs";
+import type { Phase } from "./types.js";
+import { getMilestone, getMilestoneSlices, isDbAvailable } from "./gsd-db.js";
+import { parseRoadmapSlices } from "./roadmap-slices.js";
+import { logWarning } from "./workflow-logger.js";
+
+export type MilestoneReadinessKind =
+  | "queued-shell"
+  | "needs-discussion"
+  | "planning-pending"
+  | "executable-plan"
+  | "terminal";
+
+export interface MilestoneReadiness {
+  kind: MilestoneReadinessKind;
+  hasContext: boolean;
+  hasDraftContext: boolean;
+  hasExecutablePlan: boolean;
+}
+
+export interface MilestoneReadinessInput {
+  status?: string | null;
+  hasContext?: boolean;
+  hasDraftContext?: boolean;
+  hasSummary?: boolean;
+  sliceCount?: number;
+}
+
+export interface HandoffReadinessInput {
+  milestoneId: string;
+  contextFile: string | null;
+  roadmapFile: string | null;
+}
+
+export function classifyMilestoneReadiness(input: MilestoneReadinessInput): MilestoneReadiness {
+  const hasContext = input.hasContext === true;
+  const hasDraftContext = !hasContext && input.hasDraftContext === true;
+  const hasSummary = input.hasSummary === true;
+  const sliceCount = input.sliceCount ?? 0;
+  const hasExecutablePlan = sliceCount > 0;
+  const status = input.status ?? null;
+
+  if (status === "complete" || hasSummary) {
+    return { kind: "terminal", hasContext, hasDraftContext, hasExecutablePlan };
+  }
+
+  if (status === "queued" && !hasContext && sliceCount === 0) {
+    return { kind: "queued-shell", hasContext, hasDraftContext, hasExecutablePlan };
+  }
+
+  if ((status === "needs-discussion" && !hasContext) || hasDraftContext) {
+    return { kind: "needs-discussion", hasContext, hasDraftContext, hasExecutablePlan };
+  }
+
+  if (hasExecutablePlan) {
+    return { kind: "executable-plan", hasContext, hasDraftContext, hasExecutablePlan };
+  }
+
+  return { kind: "planning-pending", hasContext, hasDraftContext, hasExecutablePlan };
+}
+
+export function readinessNeedsDiscussion(readiness: MilestoneReadiness): boolean {
+  return readiness.kind === "needs-discussion" ||
+    (readiness.kind === "queued-shell" && readiness.hasDraftContext);
+}
+
+export function describeMilestoneReadinessPhase(
+  phase: Phase,
+): { label: string; description: string } | null {
+  switch (phase) {
+    case "needs-discussion":
+      return {
+        label: "Discuss milestone draft",
+        description: "Milestone has a draft context — needs discussion before planning.",
+      };
+    case "pre-planning":
+      return {
+        label: "Research & plan milestone",
+        description: "Scout the landscape and create the roadmap.",
+      };
+    default:
+      return null;
+  }
+}
+
+function executablePlanSliceCount(milestoneId: string, roadmapFile: string | null): number {
+  if (isDbAvailable()) {
+    return getMilestoneSlices(milestoneId).length;
+  }
+  if (!roadmapFile) return 0;
+  try {
+    return parseRoadmapSlices(readFileSync(roadmapFile, "utf-8")).length;
+  } catch (e) {
+    logWarning(
+      "guided",
+      `failed to parse roadmap slices for ${milestoneId}: ${(e as Error).message}`,
+    );
+    return 0;
+  }
+}
+
+export function assessMilestoneHandoffReadiness(
+  input: HandoffReadinessInput,
+): MilestoneReadiness {
+  const milestone = isDbAvailable() ? getMilestone(input.milestoneId) : null;
+  return classifyMilestoneReadiness({
+    status: milestone?.status,
+    hasContext: input.contextFile != null,
+    sliceCount: executablePlanSliceCount(input.milestoneId, input.roadmapFile),
+  });
+}
+
+export function formatAcceptedDiscussHandoffMessage(
+  milestoneId: string,
+  readiness: MilestoneReadiness,
+): string {
+  if (readiness.hasExecutablePlan) return `Milestone ${milestoneId} ready.`;
+  if (readiness.hasContext) {
+    return `Milestone ${milestoneId} context captured. Continuing the planning pipeline.`;
+  }
+  return `Milestone ${milestoneId} planning artifacts captured. Continuing the planning pipeline.`;
+}

package/src/resources/extensions/gsd/milestone-reopen-events.ts

@@ -1,13 +1,10 @@
-import { join } from "node:path";
-
-import { gsdRoot } from "./paths.js";
+import { workflowEventArchivePath, workflowEventLogPath } from "./workflow-event-ledger.js";
 import { readEvents } from "./workflow-events.js";
 
 export function latestExplicitReopenAt(basePath: string, milestoneId: string): string | null {
-  const root = gsdRoot(basePath);
   const candidates = [
-    join(root, "event-log.jsonl"),
-    join(root, `event-log-${milestoneId}.jsonl.archived`),
+    workflowEventLogPath(basePath),
+    workflowEventArchivePath(basePath, milestoneId),
   ];
 
   let latest: string | null = null;

package/src/resources/extensions/gsd/milestone-settlement.ts

@@ -0,0 +1,81 @@
+// Project/App: gsd-pi
+// File Purpose: Milestone closeout settlement state across DB proof, artifacts, merge, and cleanup.
+
+import { isInAutoWorktree } from "./auto-worktree.js";
+import {
+  formatCloseoutProofBlock,
+  proveMilestoneCloseout,
+} from "./milestone-closeout-proof.js";
+import { resolveCloseoutArtifactProjection } from "./artifact-projection.js";
+
+export type MilestoneSettlementOutcome =
+  | { ok: true; reason: "settled" | "not-applicable" }
+  | {
+      ok: false;
+      reason: "closeout-blocked" | "merge-pending";
+      action: "pause";
+      message: string;
+      nextAction: string;
+      milestoneId: string;
+    };
+
+export interface MilestoneSettlementInput {
+  milestoneId: string | null | undefined;
+  statePhase: string;
+  basePath: string;
+  originalBasePath: string;
+  milestoneMerged: boolean;
+}
+
+function isActiveUnmergedWorktree(input: MilestoneSettlementInput): boolean {
+  if (!input.milestoneId || input.milestoneMerged) return false;
+  return isInAutoWorktree(input.basePath);
+}
+
+export function evaluateAllCompleteSettlement(
+  input: MilestoneSettlementInput,
+): MilestoneSettlementOutcome {
+  if (input.statePhase !== "complete") {
+    return { ok: true, reason: "not-applicable" };
+  }
+  if (!isActiveUnmergedWorktree(input)) {
+    return { ok: true, reason: "settled" };
+  }
+
+  const milestoneId = input.milestoneId;
+  if (!milestoneId) {
+    return { ok: true, reason: "settled" };
+  }
+
+  const projection = resolveCloseoutArtifactProjection({
+    milestoneId,
+    basePath: input.basePath,
+    originalBasePath: input.originalBasePath,
+  });
+  const proof = proveMilestoneCloseout(milestoneId, {
+    refreshFromDisk: true,
+    summaryArtifactBasePath: projection.summaryArtifactBasePath,
+  });
+
+  if (!proof.ok) {
+    return {
+      ok: false,
+      reason: "closeout-blocked",
+      action: "pause",
+      message: `${formatCloseoutProofBlock(proof)} The milestone branch has not been merged to main.`,
+      nextAction: `Resolve closeout blockers, then retry \`/gsd dispatch complete-milestone ${milestoneId}\`.`,
+      milestoneId,
+    };
+  }
+
+  return {
+    ok: false,
+    reason: "merge-pending",
+    action: "pause",
+    message:
+      `Milestone ${milestoneId} is complete, but its worktree branch has not been merged to main. ` +
+      `Retry with \`/gsd dispatch complete-milestone ${milestoneId}\` or merge manually.`,
+    nextAction: `Retry \`/gsd dispatch complete-milestone ${milestoneId}\` or merge manually.`,
+    milestoneId,
+  };
+}

package/src/resources/extensions/gsd/milestone-validation-evidence.ts

@@ -0,0 +1,95 @@
+// Project/App: gsd-pi
+// File Purpose: Forwarded validation evidence rules for milestone validation.
+
+import { getArtifact, getMilestone, getMilestoneSlices } from "./gsd-db.js";
+import { loadFile } from "./files.js";
+import { resolveSliceFile } from "./paths.js";
+import {
+  compactTextParts,
+  hasBrowserEvidenceText,
+  hasBrowserRequiredText,
+} from "./browser-evidence.js";
+
+export interface MilestoneValidationEvidenceParams {
+  milestoneId: string;
+  verdict: "pass" | "needs-attention" | "needs-remediation";
+  successCriteriaChecklist: string;
+  verificationClasses?: string;
+  verdictRationale: string;
+  remediationPlan?: string;
+}
+
+export function hasRuntimeExecutableUatEvidenceText(text: string): boolean {
+  if (!/\buatType:\s*runtime-executable\b/i.test(text)) return false;
+  if (!/\bverdict:\s*PASS\b/i.test(text)) return false;
+  return /^\|\s*[^|\n]+\s*\|\s*runtime\s*\|\s*PASS\s*\|[^|\n]*\bgsd_uat_exec\b/mi.test(text);
+}
+
+export async function browserEvidenceGateRequiresAttention(
+  params: MilestoneValidationEvidenceParams,
+  basePath: string,
+): Promise<boolean> {
+  if (params.verdict !== "pass") return false;
+
+  const milestone = getMilestone(params.milestoneId);
+  const slices = getMilestoneSlices(params.milestoneId);
+  const requirementText = compactTextParts([
+    milestone?.vision,
+    milestone?.success_criteria,
+    milestone?.verification_uat,
+    params.successCriteriaChecklist,
+    params.verificationClasses,
+    ...slices.flatMap((slice) => [
+      slice.demo,
+      slice.goal,
+      slice.success_criteria,
+    ]),
+  ]);
+  if (!hasBrowserRequiredText(requirementText)) return false;
+
+  const sliceEvidencePairs: Array<{ sliceRequirementText: string; evidenceText: string }> = [];
+  for (const slice of slices) {
+    const chunks: string[] = [];
+    const artifactPath = `milestones/${params.milestoneId}/slices/${slice.id}/${slice.id}-ASSESSMENT.md`;
+    const artifact = getArtifact(artifactPath);
+    if (artifact?.full_content) chunks.push(artifact.full_content);
+    const assessmentPath = resolveSliceFile(basePath, params.milestoneId, slice.id, "ASSESSMENT");
+    const assessmentContent = assessmentPath ? await loadFile(assessmentPath) : null;
+    if (assessmentContent) chunks.push(assessmentContent);
+    sliceEvidencePairs.push({
+      sliceRequirementText: compactTextParts([slice.demo, slice.goal, slice.success_criteria]),
+      evidenceText: chunks.join("\n\n"),
+    });
+  }
+
+  const browserRequiringSlices = sliceEvidencePairs.filter((slice) =>
+    hasBrowserRequiredText(slice.sliceRequirementText),
+  );
+  const runtimeBypasses =
+    browserRequiringSlices.length > 0
+      ? browserRequiringSlices.every((slice) => hasRuntimeExecutableUatEvidenceText(slice.evidenceText))
+      : sliceEvidencePairs.some((slice) => hasRuntimeExecutableUatEvidenceText(slice.evidenceText));
+  if (runtimeBypasses) return false;
+
+  const persistedEvidence = sliceEvidencePairs.map((slice) => slice.evidenceText).join("\n\n");
+  const validationEvidence = compactTextParts([
+    params.successCriteriaChecklist,
+    params.verificationClasses,
+    params.verdictRationale,
+    params.remediationPlan,
+  ]);
+  return !hasBrowserEvidenceText(`${persistedEvidence}\n\n${validationEvidence}`);
+}
+
+export function applyBrowserEvidenceGate<T extends MilestoneValidationEvidenceParams>(
+  params: T,
+): Omit<T, "verdict" | "verdictRationale"> & { verdict: "needs-attention"; verdictRationale: string } {
+  const note = "Browser evidence gate: Browser-observable acceptance criteria were detected, but no persisted ASSESSMENT or validation evidence recorded browser actions with assertions. Downgraded from pass to needs-attention.";
+  return {
+    ...params,
+    verdict: "needs-attention",
+    verdictRationale: params.verdictRationale.trim()
+      ? `${params.verdictRationale.trim()}\n\n${note}`
+      : note,
+  };
+}

package/src/resources/extensions/gsd/milestone-validation-verdict.ts

@@ -0,0 +1,80 @@
+// Project/App: gsd-pi
+// File Purpose: Resolve the authoritative milestone validation verdict across DB and disk projections.
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+import { resolveExpectedArtifactPath } from "./auto-artifact-paths.js";
+import { loadFile } from "./files.js";
+import { getLatestAssessmentByScope, isDbAvailable } from "./gsd-db.js";
+import { gsdProjectionRoot } from "./paths.js";
+import {
+  extractVerdict,
+  isValidMilestoneVerdict,
+  type ValidationVerdict,
+} from "./verdict-parser.js";
+import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
+import { resolveWorktreeProjectRoot } from "./worktree-root.js";
+
+function verdictFromContent(content: string | null | undefined): ValidationVerdict | undefined {
+  if (!content) return undefined;
+  const verdict = extractVerdict(content);
+  return verdict && isValidMilestoneVerdict(verdict) ? verdict : undefined;
+}
+
+function verdictFromDb(milestoneId: string): ValidationVerdict | undefined {
+  if (!isDbAvailable()) return undefined;
+  const assessment = getLatestAssessmentByScope(milestoneId, "milestone-validation");
+  const status = typeof assessment?.status === "string" ? assessment.status : undefined;
+  return status && isValidMilestoneVerdict(status) ? status : undefined;
+}
+
+async function verdictFromValidationPath(path: string | null): Promise<ValidationVerdict | undefined> {
+  if (!path || !existsSync(path)) return undefined;
+  return verdictFromContent(await loadFile(path));
+}
+
+/**
+ * Resolve the milestone validation verdict using the same authority order as
+ * DB-backed state derivation, with filesystem fallbacks that mirror
+ * `resolveExpectedArtifactPath` (canonical worktree projection, then project
+ * root). Manual `/gsd verdict` overrides persist to the DB first; a stale
+ * worktree-local VALIDATION.md must not re-block auto-mode after the override.
+ */
+export async function resolveMilestoneValidationVerdict(
+  basePath: string,
+  milestoneId: string,
+): Promise<ValidationVerdict | undefined> {
+  const dbVerdict = verdictFromDb(milestoneId);
+  if (dbVerdict) return dbVerdict;
+
+  const canonicalBase = resolveCanonicalMilestoneRoot(basePath, milestoneId);
+  const canonicalPath = resolveExpectedArtifactPath(
+    "validate-milestone",
+    milestoneId,
+    canonicalBase,
+  );
+  const canonicalVerdict = await verdictFromValidationPath(canonicalPath);
+  if (canonicalVerdict) return canonicalVerdict;
+
+  const projectRoot = resolveWorktreeProjectRoot(basePath);
+  if (projectRoot !== canonicalBase) {
+    const projectPath = resolveExpectedArtifactPath(
+      "validate-milestone",
+      milestoneId,
+      projectRoot,
+    );
+    const projectVerdict = await verdictFromValidationPath(projectPath);
+    if (projectVerdict) return projectVerdict;
+  }
+
+  // Last resort: direct canonical projection path even when resolveDir helpers
+  // have not materialized the milestone directory yet.
+  const directPath = join(
+    gsdProjectionRoot(canonicalBase),
+    "milestones",
+    milestoneId,
+    `${milestoneId}-VALIDATION.md`,
+  );
+  return verdictFromValidationPath(directPath);
+}

package/src/resources/extensions/gsd/model-cost-table.ts

@@ -25,6 +25,7 @@ export const BUNDLED_COST_TABLE: ModelCostEntry[] = [
   { id: "claude-opus-4-6", inputPer1k: 0.005, outputPer1k: 0.025, updatedAt: "2026-04-16" },
   { id: "claude-opus-4-7", inputPer1k: 0.005, outputPer1k: 0.025, updatedAt: "2026-04-16" },
   { id: "claude-opus-4-8", inputPer1k: 0.005, outputPer1k: 0.025, updatedAt: "2026-05-28" },
+  { id: "claude-fable-5", inputPer1k: 0.010, outputPer1k: 0.050, updatedAt: "2026-06-09" },
   { id: "claude-sonnet-4-6", inputPer1k: 0.003, outputPer1k: 0.015, updatedAt: "2025-03-15" },
   { id: "claude-haiku-4-5", inputPer1k: 0.0008, outputPer1k: 0.004, updatedAt: "2025-03-15" },
   { id: "claude-sonnet-4-5-20250514", inputPer1k: 0.003, outputPer1k: 0.015, updatedAt: "2025-03-15" },

package/src/resources/extensions/gsd/model-router.ts

@@ -101,6 +101,7 @@ export const MODEL_CAPABILITY_TIER: Record<string, ComplexityTier> = {
   "claude-opus-4-6": "heavy",
   "claude-opus-4-7": "heavy",
   "claude-opus-4-8": "heavy",
+  "claude-fable-5": "heavy",
   "claude-3-opus-latest": "heavy",
   "gpt-4-turbo": "heavy",
   "gpt-5": "heavy",
@@ -129,6 +130,7 @@ const MODEL_COST_PER_1K_INPUT: Record<string, number> = {
   "claude-opus-4-6": 0.005,
   "claude-opus-4-7": 0.005,
   "claude-opus-4-8": 0.005,
+  "claude-fable-5": 0.010,
   "gpt-4o-mini": 0.00015,
   "gpt-4o": 0.0025,
   "gpt-4.1": 0.002,
@@ -164,6 +166,7 @@ export const MODEL_CAPABILITY_PROFILES: Record<string, ModelCapabilities> = {
   "claude-opus-4-6":              { coding: 95, debugging: 90, research: 85, reasoning: 95, speed: 30, longContext: 80, instruction: 90 },
   "claude-opus-4-7":              { coding: 95, debugging: 90, research: 85, reasoning: 95, speed: 30, longContext: 80, instruction: 90 },
   "claude-opus-4-8":              { coding: 97, debugging: 92, research: 87, reasoning: 97, speed: 30, longContext: 85, instruction: 92 },
+  "claude-fable-5":               { coding: 97, debugging: 92, research: 87, reasoning: 97, speed: 30, longContext: 85, instruction: 92 },
   "claude-sonnet-4-6":            { coding: 85, debugging: 80, research: 75, reasoning: 80, speed: 60, longContext: 75, instruction: 85 },
   "claude-sonnet-4-5-20250514":   { coding: 85, debugging: 80, research: 75, reasoning: 80, speed: 60, longContext: 75, instruction: 85 },
   "claude-3-5-sonnet-latest":     { coding: 82, debugging: 78, research: 72, reasoning: 78, speed: 62, longContext: 70, instruction: 82 },

package/src/resources/extensions/gsd/native-git-bridge.ts

@@ -13,6 +13,7 @@ import { GSDError, GSD_GIT_ERROR } from "./errors.js";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 import { getErrorMessage } from "./error-utils.js";
 import { isInfrastructureError } from "./auto/infra-errors.js";
+import { debugCount } from "./debug-logger.js";
 
 // Issue #453: keep auto-mode bookkeeping on the stable git CLI path unless a
 // caller explicitly opts into the native helper.
@@ -140,6 +141,8 @@ function loadNative(): typeof nativeModule {
 
 /** Run a git command via execFileSync. Returns trimmed stdout. */
 function gitExec(basePath: string, args: string[], allowFailure = false): string {
+  // Counts git CLI shell-outs only (native libgit2 paths bypass this helper).
+  debugCount("gitInvocations");
   try {
     return execFileSync("git", args, {
       cwd: basePath,
@@ -169,6 +172,8 @@ function execGitFileSyncWithRetry(
   args: string[],
   options: Partial<ExecFileSyncOptionsWithStringEncoding>,
 ): string {
+  // Counts git CLI shell-outs only (native libgit2 paths bypass this helper).
+  debugCount("gitInvocations");
   try {
     return execFileSync("git", args, {
       cwd: basePath,
@@ -180,6 +185,8 @@ function execGitFileSyncWithRetry(
   } catch (err) {
     if (!isRetryableGitError(err)) throw err;
     sleepSync(GIT_RETRY_DELAY_MS);
+    // Retry is a second physical shell-out — count it too.
+    debugCount("gitInvocations");
     return execFileSync("git", args, {
       cwd: basePath,
       stdio: ["ignore", "pipe", "pipe"],
@@ -192,6 +199,8 @@ function execGitFileSyncWithRetry(
 
 /** Run a git command via execFileSync. Returns trimmed stdout. */
 function gitFileExec(basePath: string, args: string[], allowFailure = false): string {
+  // Counts git CLI shell-outs only (native libgit2 paths bypass this helper).
+  debugCount("gitInvocations");
   try {
     return execFileSync("git", args, {
       cwd: basePath,
@@ -1092,6 +1101,45 @@ export function nativeMergeSquash(basePath: string, branch: string): GitMergeRes
   }
 }
 
+/**
+ * Regular (non-squash) merge a branch (stages changes, does NOT commit).
+ * Uses --no-ff to ensure a proper merge commit and --no-commit so the caller
+ * can supply a custom commit message via nativeCommit.
+ * Respects the user's global git merge.ff config; --no-ff is additive here.
+ */
+export function nativeMergeRegular(basePath: string, branch: string): GitMergeResult {
+  try {
+    execFileSync("git", ["merge", "--no-ff", "--no-commit", branch], {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+      env: GIT_NO_PROMPT_ENV,
+    });
+    return { success: true, conflicts: [] };
+  } catch (err: unknown) {
+    const stderr =
+      err instanceof Error ? (err as Error & { stderr?: string }).stderr ?? err.message : String(err);
+    if (
+      stderr.includes("local changes would be overwritten") ||
+      stderr.includes("not possible because you have unmerged files") ||
+      stderr.includes("overwritten by merge")
+    ) {
+      const dirtyFiles = stderr
+        .split("\n")
+        .filter((line) => line.startsWith("\t"))
+        .map((line) => line.trim())
+        .filter(Boolean);
+      return { success: false, conflicts: ["__dirty_working_tree__"], dirtyFiles };
+    }
+    const conflictOutput = gitExec(basePath, ["diff", "--name-only", "--diff-filter=U"], true);
+    const conflicts = conflictOutput ? conflictOutput.split("\n").filter(Boolean) : [];
+    if (conflicts.length > 0) {
+      return { success: false, conflicts };
+    }
+    throw err;
+  }
+}
+
 /**
  * Abort an in-progress merge.
  * Native: libgit2 reset + cleanup.

package/src/resources/extensions/gsd/notification-store.ts

@@ -12,6 +12,17 @@ import { randomUUID } from "node:crypto";
 export type NotifySeverity = "info" | "success" | "warning" | "error";
 export type NotificationSource = "notify" | "workflow-logger";
 
+/**
+ * Optional structured identity for a notification. When present, `kind`
+ * (a stable machine name like "auto-stop" or "provider-error-pause") plus
+ * `scope` (e.g. a milestone/slice id) — not the prose — key deduplication,
+ * and consumers can filter without parsing message text.
+ */
+export interface NotificationMeta {
+  kind?: string;
+  scope?: string;
+}
+
 export interface NotificationEntry {
   id: string;
   ts: string;
@@ -19,6 +30,8 @@ export interface NotificationEntry {
   message: string;
   source: NotificationSource;
   read: boolean;
+  kind?: string;
+  scope?: string;
 }
 
 // ─── Constants ──────────────────────────────────────────────────────────
@@ -60,11 +73,15 @@ export function appendNotification(
   message: string,
   severity: NotifySeverity,
   source: NotificationSource = "notify",
+  meta?: NotificationMeta,
 ): void {
   if (!_basePath) return;
   if (_suppressCount > 0) return;
   const persistedMessage = message.length > 500 ? message.slice(0, 500) + "…" : message;
-  const dedupKey = `${_basePath}:${severity}:${source}:${persistedMessage}`;
+  // Structured identity (kind + scope) keys dedup when present, so a rephrased
+  // message of the same event still dedups; otherwise fall back to the prose.
+  const identity = meta?.kind ? `${meta.kind}:${meta.scope ?? ""}` : persistedMessage;
+  const dedupKey = `${_basePath}:${severity}:${source}:${identity}`;
   const now = Date.now();
   const lastSeen = _recentMessageTimestamps.get(dedupKey);
   if (lastSeen !== undefined && now - lastSeen < DEDUP_WINDOW_MS) return;
@@ -82,6 +99,8 @@ export function appendNotification(
     message: persistedMessage,
     source,
     read: false,
+    ...(meta?.kind ? { kind: meta.kind } : {}),
+    ...(meta?.scope ? { scope: meta.scope } : {}),
   };
 
   try {
@@ -102,11 +121,15 @@ export function appendNotification(
 
 /**
  * Read all notification entries from disk. Returns newest-first.
+ * An optional filter narrows by structured identity (kind and/or scope).
  */
-export function readNotifications(basePath?: string): NotificationEntry[] {
+export function readNotifications(basePath?: string, filter?: NotificationMeta): NotificationEntry[] {
   const bp = basePath ?? _basePath;
   if (!bp) return [];
-  return _readEntriesFromDisk(bp).reverse();
+  const entries = _readEntriesFromDisk(bp).filter(
+    (e) => (!filter?.kind || e.kind === filter.kind) && (!filter?.scope || e.scope === filter.scope),
+  );
+  return entries.reverse();
 }
 
 /**

package/src/resources/extensions/gsd/parallel-eligibility.ts

@@ -5,11 +5,11 @@
  * dependency satisfaction and file overlap across slice plans.
  */
 
-import { existsSync } from "node:fs";
 import { deriveState } from "./state.js";
-import { resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "./paths.js";
+import { resolveMilestoneFile, resolveSliceFile } from "./paths.js";
 import { findMilestoneIds } from "./guided-flow.js";
-import { isDbAvailable, getMilestoneSlices, getSliceTasks, openDatabase } from "./gsd-db.js";
+import { isDbAvailable, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
+import { openExistingWorkflowDatabase } from "./db-workspace.js";
 import type { MilestoneRegistryEntry } from "./types.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
@@ -98,8 +98,7 @@ export async function analyzeParallelEligibility(
   basePath: string,
 ): Promise<ParallelCandidates> {
   if (!isDbAvailable()) {
-    const { projectDb } = resolveGsdPathContract(basePath);
-    if (existsSync(projectDb)) openDatabase(projectDb);
+    openExistingWorkflowDatabase(basePath);
   }
 
   const milestoneIds = findMilestoneIds(basePath);

package/src/resources/extensions/gsd/parallel-merge.ts

@@ -9,6 +9,7 @@ import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
 import { resolveGsdPathContract } from "./paths.js";
+import { worktreePathFor, worktreesDirs } from "./worktree-placement.js";
 import { getAutoWorktreePath } from "./auto-worktree.js";
 import { buildWorktreeLifecycleDeps } from "./auto.js";
 import {
@@ -42,7 +43,7 @@ export type MergeOrder = "sequential" | "by-completion";
  * Returns true when milestones.status = 'complete' in project gsd.db.
  */
 export function isMilestoneCompleteInProjectDb(basePath: string, mid: string): boolean {
-  const workRoot = join(basePath, ".gsd", "worktrees", mid);
+  const workRoot = worktreePathFor(basePath, mid);
   const dbPath = resolveGsdPathContract(workRoot, basePath).projectDb;
   if (!existsSync(dbPath)) return false;
 
@@ -65,15 +66,17 @@ export function isMilestoneCompleteInProjectDb(basePath: string, mid: string): b
  */
 function discoverDbCompletedMilestones(basePath: string): Set<string> {
   const completed = new Set<string>();
-  const worktreeDir = join(basePath, ".gsd", "worktrees");
-  try {
-    for (const entry of readdirSync(worktreeDir)) {
-      if (entry.startsWith("M") && isMilestoneCompleteInProjectDb(basePath, entry)) {
-        completed.add(entry);
+  for (const worktreeDir of worktreesDirs(basePath)) {
+    if (!existsSync(worktreeDir)) continue;
+    try {
+      for (const entry of readdirSync(worktreeDir)) {
+        if (entry.startsWith("M") && isMilestoneCompleteInProjectDb(basePath, entry)) {
+          completed.add(entry);
+        }
       }
+    } catch (e) {
+      logWarning("parallel", `readdirSync for completed set failed: ${(e as Error).message}`);
     }
-  } catch (e) {
-    logWarning("parallel", `readdirSync for completed set failed: ${(e as Error).message}`);
   }
   return completed;
 }
@@ -120,7 +123,7 @@ export function determineMergeOrder(
         title: mid,
         pid: 0,
         process: null,
-        worktreePath: basePath ? join(basePath, ".gsd", "worktrees", mid) : "",
+        worktreePath: basePath ? worktreePathFor(basePath, mid) : "",
         startedAt: 0,
         state: "stopped",
         cost: 0,