gsd-pi 2.77.0-dev.538325aea → 2.77.0-dev.58d3d4d6c

package/src/resources/extensions/gsd/uok/loop-adapter.ts

@@ -6,6 +6,7 @@ import type {
 } from "./contracts.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
 import { writeTurnCloseoutGitRecord, writeTurnGitTransaction } from "./gitops.js";
+import { acquireWriterToken, nextWriteRecord, releaseWriterToken } from "./writer.js";
 
 export interface CreateTurnObserverOptions {
   basePath: string;
@@ -17,12 +18,38 @@ export interface CreateTurnObserverOptions {
 
 export function createTurnObserver(options: CreateTurnObserverOptions): UokTurnObserver {
   let current: TurnContract | null = null;
+  let writerToken: ReturnType<typeof acquireWriterToken> | null = null;
   const phaseResults: TurnResult["phaseResults"] = [];
 
+  function nextSequenceMetadata(
+    category: "audit" | "gitops",
+    operation: "append" | "insert" | "update",
+    metadata?: Record<string, unknown>,
+  ): Record<string, unknown> {
+    if (!writerToken) return metadata ?? {};
+    const record = nextWriteRecord({
+      basePath: options.basePath,
+      token: writerToken,
+      category,
+      operation,
+      metadata,
+    });
+    return {
+      ...(metadata ?? {}),
+      writeSequence: record.sequence.sequence,
+      writerTokenId: record.writerToken.tokenId,
+    };
+  }
+
   return {
     onTurnStart(contract): void {
       current = contract;
       phaseResults.length = 0;
+      writerToken = acquireWriterToken({
+        basePath: options.basePath,
+        traceId: contract.traceId,
+        turnId: contract.turnId,
+      });
 
       if (options.enableGitops) {
         writeTurnGitTransaction({
@@ -35,10 +62,10 @@ export function createTurnObserver(options: CreateTurnObserverOptions): UokTurnO
           action: options.gitAction,
           push: options.gitPush,
           status: "ok",
-          metadata: {
+          metadata: nextSequenceMetadata("gitops", "insert", {
             iteration: contract.iteration,
             sidecarKind: contract.sidecarKind,
-          },
+          }),
         });
       }
 
@@ -50,12 +77,12 @@ export function createTurnObserver(options: CreateTurnObserverOptions): UokTurnO
             turnId: contract.turnId,
             category: "orchestration",
             type: "turn-start",
-            payload: {
+            payload: nextSequenceMetadata("audit", "append", {
               iteration: contract.iteration,
               unitType: contract.unitType,
               unitId: contract.unitId,
               sidecarKind: contract.sidecarKind,
-            },
+            }),
           }),
         );
       }
@@ -81,7 +108,7 @@ export function createTurnObserver(options: CreateTurnObserverOptions): UokTurnO
           action: options.gitAction,
           push: options.gitPush,
           status: "ok",
-          metadata: { action },
+          metadata: nextSequenceMetadata("gitops", "update", { action }),
         });
       }
       if (phase === "unit") {
@@ -95,7 +122,7 @@ export function createTurnObserver(options: CreateTurnObserverOptions): UokTurnO
           action: options.gitAction,
           push: options.gitPush,
           status: "ok",
-          metadata: { action },
+          metadata: nextSequenceMetadata("gitops", "update", { action }),
         });
       }
       if (phase === "finalize") {
@@ -109,7 +136,7 @@ export function createTurnObserver(options: CreateTurnObserverOptions): UokTurnO
           action: options.gitAction,
           push: options.gitPush,
           status: "ok",
-          metadata: { action },
+          metadata: nextSequenceMetadata("gitops", "update", { action }),
         });
       }
     },
@@ -128,14 +155,14 @@ export function createTurnObserver(options: CreateTurnObserverOptions): UokTurnO
             turnId: merged.turnId,
             category: "orchestration",
             type: "turn-result",
-            payload: {
+            payload: nextSequenceMetadata("audit", "append", {
               unitType: merged.unitType,
               unitId: merged.unitId,
               status: merged.status,
               failureClass: merged.failureClass,
               error: merged.error,
               phaseCount: merged.phaseResults.length,
-            },
+            }),
           }),
         );
       }
@@ -152,9 +179,17 @@ export function createTurnObserver(options: CreateTurnObserverOptions): UokTurnO
           gitPushed: options.gitPush,
           finishedAt: merged.finishedAt,
         };
-        writeTurnCloseoutGitRecord(options.basePath, closeout);
+        writeTurnCloseoutGitRecord(
+          options.basePath,
+          closeout,
+          nextSequenceMetadata("gitops", "update", { action: "record" }),
+        );
       }
 
+      if (writerToken) {
+        releaseWriterToken(options.basePath, writerToken);
+      }
+      writerToken = null;
       current = null;
       phaseResults.length = 0;
     },

package/src/resources/extensions/gsd/uok/parity-report.ts

@@ -0,0 +1,84 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { gsdRoot } from "../paths.js";
+
+export interface UokParityEvent {
+  ts?: string;
+  path?: string;
+  phase?: string;
+  status?: string;
+  error?: string;
+  flags?: Record<string, unknown>;
+}
+
+export interface UokParityReport {
+  generatedAt: string;
+  sourcePath: string;
+  totalEvents: number;
+  paths: Record<string, number>;
+  statuses: Record<string, number>;
+  criticalMismatches: string[];
+  fallbackInvocations: number;
+}
+
+function parityLogPath(basePath: string): string {
+  return join(gsdRoot(basePath), "runtime", "uok-parity.jsonl");
+}
+
+function reportPath(basePath: string): string {
+  return join(gsdRoot(basePath), "runtime", "uok-parity-report.json");
+}
+
+function increment(bucket: Record<string, number>, key: string | undefined): void {
+  const normalized = key && key.trim().length > 0 ? key : "unknown";
+  bucket[normalized] = (bucket[normalized] ?? 0) + 1;
+}
+
+export function parseParityEvents(raw: string): UokParityEvent[] {
+  return raw
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line) as UokParityEvent;
+      } catch {
+        return { status: "error", error: "invalid parity json line" };
+      }
+    });
+}
+
+export function buildParityReport(events: readonly UokParityEvent[], sourcePath: string): UokParityReport {
+  const paths: Record<string, number> = {};
+  const statuses: Record<string, number> = {};
+  const criticalMismatches: string[] = [];
+  let fallbackInvocations = 0;
+
+  for (const event of events) {
+    increment(paths, event.path);
+    increment(statuses, event.status);
+    if (event.path === "legacy-fallback") fallbackInvocations += 1;
+    if (event.status === "error") {
+      criticalMismatches.push(event.error ?? "parity event reported error");
+    }
+  }
+
+  return {
+    generatedAt: new Date().toISOString(),
+    sourcePath,
+    totalEvents: events.length,
+    paths,
+    statuses,
+    criticalMismatches,
+    fallbackInvocations,
+  };
+}
+
+export function writeParityReport(basePath: string): UokParityReport {
+  const sourcePath = parityLogPath(basePath);
+  const raw = existsSync(sourcePath) ? readFileSync(sourcePath, "utf-8") : "";
+  const report = buildParityReport(parseParityEvents(raw), sourcePath);
+  mkdirSync(join(gsdRoot(basePath), "runtime"), { recursive: true });
+  writeFileSync(reportPath(basePath), JSON.stringify(report, null, 2) + "\n", "utf-8");
+  return report;
+}

package/src/resources/extensions/gsd/uok/plan-v2.ts

@@ -7,13 +7,17 @@ import { isDbAvailable, getMilestoneSlices, getSliceTasks, type SliceRow } from
 import type { UokGraphNode } from "./contracts.js";
 
 const PLAN_V2_CLARIFY_ROUND_LIMIT = 3;
-const EXECUTION_ENTRY_PHASES: ReadonlySet<Phase> = new Set([
+export const EXECUTION_ENTRY_PHASES: ReadonlySet<Phase> = new Set([
   "executing",
   "summarizing",
   "validating-milestone",
   "completing-milestone",
 ]);
 
+export function isExecutionEntryPhase(phase: Phase): boolean {
+  return EXECUTION_ENTRY_PHASES.has(phase);
+}
+
 export interface PlanV2CompileResult {
   ok: boolean;
   reason?: string;
@@ -61,6 +65,14 @@ function hasMilestoneFileContent(
   return false;
 }
 
+export function hasFinalizedMilestoneContext(basePath: string, milestoneId: string): boolean {
+  return hasMilestoneFileContent(basePath, milestoneId, "CONTEXT");
+}
+
+export function isMissingFinalizedContextResult(result: PlanV2CompileResult): boolean {
+  return !result.ok && result.finalizedContextIncluded === false;
+}
+
 function countSliceResearchArtifacts(basePath: string, milestoneId: string, slices: SliceRow[]): number {
   let count = 0;
   for (const slice of slices) {
@@ -71,10 +83,6 @@ function countSliceResearchArtifacts(basePath: string, milestoneId: string, slic
   return count;
 }
 
-function isExecutionEntryPhase(phase: Phase): boolean {
-  return EXECUTION_ENTRY_PHASES.has(phase);
-}
-
 export function compileUnitGraphFromState(basePath: string, state: GSDState): PlanV2CompileResult {
   const mid = state.activeMilestone?.id;
   if (!mid) return { ok: false, reason: "no active milestone" };

package/src/resources/extensions/gsd/uok/writer.ts

@@ -0,0 +1,113 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+
+import { atomicWriteSync } from "../atomic-write.js";
+import { gsdRoot } from "../paths.js";
+import type { WriteRecord, WriterToken } from "./contracts.js";
+
+interface SequenceState {
+  lastSequence: number;
+  updatedAt: string;
+}
+
+const activeTokens = new Map<string, WriterToken>();
+
+function tokenKey(basePath: string, turnId: string): string {
+  return `${basePath}:${turnId}`;
+}
+
+function sequencePath(basePath: string): string {
+  return join(gsdRoot(basePath), "runtime", "uok-writer-sequence.json");
+}
+
+function readSequenceState(basePath: string): SequenceState {
+  const path = sequencePath(basePath);
+  if (!existsSync(path)) {
+    return { lastSequence: 0, updatedAt: new Date(0).toISOString() };
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8")) as Partial<SequenceState>;
+    return {
+      lastSequence: Number.isInteger(parsed.lastSequence) ? Number(parsed.lastSequence) : 0,
+      updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : new Date(0).toISOString(),
+    };
+  } catch {
+    return { lastSequence: 0, updatedAt: new Date(0).toISOString() };
+  }
+}
+
+function writeSequenceState(basePath: string, state: SequenceState): void {
+  atomicWriteSync(sequencePath(basePath), JSON.stringify(state, null, 2) + "\n", "utf-8");
+}
+
+export function acquireWriterToken(args: {
+  basePath: string;
+  traceId: string;
+  turnId: string;
+  owner?: WriterToken["owner"];
+}): WriterToken {
+  const key = tokenKey(args.basePath, args.turnId);
+  const existing = activeTokens.get(key);
+  if (existing) {
+    throw new Error(`Writer token already active for turn ${args.turnId}`);
+  }
+
+  const token: WriterToken = {
+    tokenId: randomUUID(),
+    traceId: args.traceId,
+    turnId: args.turnId,
+    acquiredAt: new Date().toISOString(),
+    owner: args.owner ?? "uok",
+  };
+  activeTokens.set(key, token);
+  return token;
+}
+
+export function releaseWriterToken(basePath: string, token: WriterToken): void {
+  const key = tokenKey(basePath, token.turnId);
+  const current = activeTokens.get(key);
+  if (current?.tokenId === token.tokenId) {
+    activeTokens.delete(key);
+  }
+}
+
+export function hasActiveWriterToken(basePath: string, turnId: string): boolean {
+  return activeTokens.has(tokenKey(basePath, turnId));
+}
+
+export function nextWriteRecord(args: {
+  basePath: string;
+  token: WriterToken;
+  category: WriteRecord["category"];
+  operation: WriteRecord["operation"];
+  path?: string;
+  metadata?: Record<string, unknown>;
+}): WriteRecord {
+  if (!hasActiveWriterToken(args.basePath, args.token.turnId)) {
+    throw new Error(`Writer token is not active for turn ${args.token.turnId}`);
+  }
+
+  const state = readSequenceState(args.basePath);
+  const sequence = state.lastSequence + 1;
+  const updatedAt = new Date().toISOString();
+  writeSequenceState(args.basePath, { lastSequence: sequence, updatedAt });
+
+  return {
+    writerToken: args.token,
+    sequence: {
+      traceId: args.token.traceId,
+      turnId: args.token.turnId,
+      sequence,
+    },
+    category: args.category,
+    operation: args.operation,
+    path: args.path,
+    ts: updatedAt,
+    metadata: args.metadata,
+  };
+}
+
+export function resetWriterTokensForTests(): void {
+  activeTokens.clear();
+}

package/src/resources/extensions/gsd/workflow-logger.ts

@@ -16,9 +16,17 @@
 // the start of each unit to prevent log bleed between units running in the same
 // Node process.
 
-import { appendFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
+import {
+  appendFileSync,
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+} from "node:fs";
 import { join } from "node:path";
 
+import { withFileLockSync } from "./file-lock.js";
 import { appendNotification } from "./notification-store.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./uok/audit.js";
 import { isUnifiedAuditEnabled } from "./uok/audit-toggle.js";
@@ -59,7 +67,8 @@ export type LogComponent =
   | "memory-ingest"     // Memory layer ingestion pipeline
   | "memory-backfill"   // ADR-013: decisions->memories backfill
   | "context-mode"     // Context-mode exec sandbox and compaction snapshot
-  | "preflight";       // Clean-root preflight gate at milestone completion
+  | "preflight"        // Clean-root preflight gate at milestone completion
+  | "postUnit";     // Post-unit processing (abandon detection, overrides)
 
 export interface LogEntry {
   ts: string;
@@ -313,8 +322,18 @@ function _push(
     try {
       const auditDir = join(_auditBasePath, ".gsd");
       mkdirSync(auditDir, { recursive: true });
+      const auditPath = join(auditDir, "audit-log.jsonl");
       const sanitized = _sanitizeForAudit(entry);
-      appendFileSync(join(auditDir, "audit-log.jsonl"), JSON.stringify(sanitized) + "\n", "utf-8");
+      // Ensure file exists so proper-lockfile can acquire a lock against it.
+      if (!existsSync(auditPath)) closeSync(openSync(auditPath, "a"));
+      // onLocked: "skip" — never block error logging on lock contention.
+      withFileLockSync(
+        auditPath,
+        () => {
+          appendFileSync(auditPath, JSON.stringify(sanitized) + "\n", "utf-8");
+        },
+        { onLocked: "skip" },
+      );
     } catch (auditErr) {
       // Best-effort — never let audit write failures bubble up
       _writeStderr(`[gsd:audit] failed to persist log entry: ${(auditErr as Error).message}\n`);

package/src/resources/extensions/gsd/worktree-manager.ts

@@ -37,6 +37,7 @@ import {
   nativeWorktreePrune,
   nativeWorktreeRemove,
 } from "./native-git-bridge.js";
+import { emitCanonicalRootRedirect } from "./worktree-telemetry.js";
 
 // ─── Types ─────────────────────────────────────────────────────────────────
 
@@ -132,6 +133,58 @@ export function isInsideWorktreesDir(basePath: string, targetPath: string): bool
   return resolved === wtDir || resolved.startsWith(wtDir + sep);
 }
 
+/**
+ * Return the canonical path from which a milestone's artifacts should be read.
+ *
+ * If a live git worktree exists for this milestone at `.gsd/worktrees/<MID>/`
+ * (directory present AND a `.git` file indicating a registered worktree),
+ * returns that worktree path. Otherwise returns `basePath` unchanged.
+ *
+ * Readers that cross the session/worktree boundary (validators, the bootstrap
+ * audit, cross-session state queries) should route through this helper so they
+ * don't silently read stale project-root state while live work sits in the
+ * worktree. Writers and tools whose contract is "operate on the path I was
+ * given" should NOT use this helper — they preserve the legacy behavior.
+ *
+ * A stale worktree directory (no `.git` file) is treated as absent. The
+ * createWorktree() path already cleans these up, but readers must not trust
+ * them in the window before cleanup runs.
+ *
+ * Fixes #4761. Used by the #4762 audit for the pre-completion orphan case.
+ */
+export function resolveCanonicalMilestoneRoot(
+  basePath: string,
+  milestoneId: string,
+): string {
+  if (!milestoneId || /[\/\\]|\.\./.test(milestoneId)) return basePath;
+
+  const wtPath = worktreePath(basePath, milestoneId);
+  if (!existsSync(wtPath)) return basePath;
+
+  // A registered git worktree has a .git *file* (not directory) containing
+  // "gitdir: <path>". A standalone .git directory indicates a copied repo
+  // or nested standalone repo — not a worktree registered with this project —
+  // and must not be treated as the canonical root.
+  const gitPath = join(wtPath, ".git");
+  if (!existsSync(gitPath)) return basePath;
+  try {
+    const stat = lstatSync(gitPath);
+    if (!stat.isFile()) return basePath;
+  } catch {
+    return basePath;
+  }
+
+  // #4764 — record the redirect so we can measure how often the #4761 fix
+  // would have mattered. Best-effort; emit is silent on any failure.
+  try {
+    emitCanonicalRootRedirect(basePath, milestoneId, wtPath);
+  } catch (err) {
+    logWarning("worktree", `canonical-root-redirect telemetry failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  return wtPath;
+}
+
 // ─── Core Operations ───────────────────────────────────────────────────────
 
 /**
@@ -559,6 +612,7 @@ const SKIP_PATHS = [
   ".gsd/worktrees/",
   ".gsd/runtime/",
   ".gsd/activity/",
+  ".gsd/audit/",
   ".gsd/forensics/",
   ".gsd/parallel/",
   ".gsd/journal/",

package/src/resources/extensions/gsd/worktree-resolver.ts

@@ -20,6 +20,9 @@ import type { AutoSession } from "./auto/session.js";
 import { debugLog } from "./debug-logger.js";
 import { MergeConflictError } from "./git-service.js";
 import { emitJournalEvent } from "./journal.js";
+import { emitWorktreeCreated, emitWorktreeMerged } from "./worktree-telemetry.js";
+import { getCollapseCadence, getMilestoneResquash, resquashMilestoneOnMain } from "./slice-cadence.js";
+import { loadEffectiveGSDPreferences } from "./preferences.js";
 
 // ─── Dependency Interface ──────────────────────────────────────────────────
 
@@ -290,6 +293,19 @@ export class WorktreeResolver {
         eventType: "worktree-enter",
         data: { milestoneId, wtPath, created: !existingPath },
       });
+      // #4764 — record creation/enter as a lifecycle event so the telemetry
+      // aggregator can pair it with the eventual worktree-merged event.
+      try {
+        emitWorktreeCreated(this.s.originalBasePath || this.s.basePath, milestoneId, {
+          reason: existingPath ? "enter-milestone" : "create-milestone",
+        });
+      } catch (telemetryErr) {
+        debugLog("WorktreeResolver", {
+          action: "enterMilestone",
+          phase: "telemetry-emit",
+          error: telemetryErr instanceof Error ? telemetryErr.message : String(telemetryErr),
+        });
+      }
       ctx.notify(`Entered worktree for ${milestoneId} at ${wtPath}`, "info");
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
@@ -398,6 +414,10 @@ export class WorktreeResolver {
   mergeAndExit(milestoneId: string, ctx: NotifyCtx): void {
     this.validateMilestoneId(milestoneId);
 
+    // #4764 — telemetry: record start timestamp so we can emit merge duration.
+    const mergeStartedAt = new Date().toISOString();
+    const mergeStartMs = Date.now();
+
     // If worktree creation failed earlier, skip merge — work is on current branch (#2483)
     if (this.s.isolationDegraded) {
       debugLog("WorktreeResolver", {
@@ -444,17 +464,79 @@ export class WorktreeResolver {
       return;
     }
 
+    let actuallyMerged = false;
     if (
       mode === "worktree" || inWorktree
     ) {
-      this._mergeWorktreeMode(milestoneId, ctx);
+      actuallyMerged = this._mergeWorktreeMode(milestoneId, ctx);
     } else if (mode === "branch") {
-      this._mergeBranchMode(milestoneId, ctx);
+      actuallyMerged = this._mergeBranchMode(milestoneId, ctx);
+    }
+
+    // The remainder of this function emits telemetry and runs re-squash.
+    // Both are gated on actuallyMerged — if the _merge* helper took a
+    // no-merge path (missing originalBase, no roadmap, wrong branch) the
+    // milestone branch was intentionally left unmerged and we must not
+    // emit a worktree-merged event or collapse commits on main.
+    if (!actuallyMerged) {
+      // Always clear the start-SHA tracker to avoid leaking across sessions.
+      this.s.milestoneStartShas.delete(milestoneId);
+      return;
+    }
+
+    // #4765 — when collapse_cadence=slice AND milestone_resquash=true, the
+    // N per-slice commits on main should be collapsed into one milestone
+    // commit. Done AFTER the primary merge-and-teardown so the branch and
+    // worktree are already cleaned up; we operate on main directly.
+    try {
+      const startSha = this.s.milestoneStartShas.get(milestoneId);
+      if (startSha) {
+        const prefs = loadEffectiveGSDPreferences(this.s.originalBasePath || this.s.basePath)?.preferences;
+        if (getCollapseCadence(prefs) === "slice" && getMilestoneResquash(prefs)) {
+          const result = resquashMilestoneOnMain(
+            this.s.originalBasePath || this.s.basePath,
+            milestoneId,
+            startSha,
+          );
+          if (result.resquashed) {
+            ctx.notify(
+              `slice-cadence: re-squashed slice commits for ${milestoneId} into a single milestone commit.`,
+              "info",
+            );
+          }
+        }
+        this.s.milestoneStartShas.delete(milestoneId);
+      }
+    } catch (err) {
+      debugLog("WorktreeResolver", {
+        action: "mergeAndExit",
+        milestoneId,
+        phase: "resquash",
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+
+    // #4764 — record merge completion. Only reaches here when an actual
+    // merge ran; failure paths throw out of _merge* before this point and
+    // no-merge paths returned above.
+    try {
+      emitWorktreeMerged(this.s.originalBasePath || this.s.basePath, milestoneId, {
+        reason: "milestone-complete",
+        startedAt: mergeStartedAt,
+        durationMs: Date.now() - mergeStartMs,
+      });
+    } catch (telemetryErr) {
+      debugLog("WorktreeResolver", {
+        action: "mergeAndExit",
+        phase: "telemetry-emit",
+        error: telemetryErr instanceof Error ? telemetryErr.message : String(telemetryErr),
+      });
     }
   }
 
-  /** Worktree-mode merge: read roadmap, merge, teardown, reset paths. */
-  private _mergeWorktreeMode(milestoneId: string, ctx: NotifyCtx): void {
+  /** Worktree-mode merge: read roadmap, merge, teardown, reset paths.
+   *  Returns true when a squash-merge actually ran (false on skip paths). */
+  private _mergeWorktreeMode(milestoneId: string, ctx: NotifyCtx): boolean {
     const originalBase = this.s.originalBasePath;
     if (!originalBase) {
       debugLog("WorktreeResolver", {
@@ -464,9 +546,10 @@ export class WorktreeResolver {
         skipped: true,
         reason: "missing-original-base",
       });
-      return;
+      return false;
     }
 
+    let merged = false;
     try {
       const { synced } = this.deps.syncWorktreeStateBack(
         originalBase,
@@ -515,6 +598,7 @@ export class WorktreeResolver {
           milestoneId,
           roadmapContent,
         );
+        merged = true;
 
         // #2945 Bug 3: mergeMilestoneToMain performs best-effort worktree
         // cleanup internally (step 12), but it can silently fail on Windows
@@ -618,10 +702,12 @@ export class WorktreeResolver {
       result: "done",
       basePath: this.s.basePath,
     });
+    return merged;
   }
 
-  /** Branch-mode merge: check current branch, merge if on milestone branch. */
-  private _mergeBranchMode(milestoneId: string, ctx: NotifyCtx): void {
+  /** Branch-mode merge: check current branch, merge if on milestone branch.
+   *  Returns true when a merge actually ran (false on skip paths). */
+  private _mergeBranchMode(milestoneId: string, ctx: NotifyCtx): boolean {
     try {
       const currentBranch = this.deps.getCurrentBranch(this.s.basePath);
       const milestoneBranch = this.deps.autoWorktreeBranch(milestoneId);
@@ -636,7 +722,7 @@ export class WorktreeResolver {
           currentBranch,
           milestoneBranch,
         });
-        return;
+        return false;
       }
 
       const roadmapPath = this.deps.resolveMilestoneFile(
@@ -652,7 +738,7 @@ export class WorktreeResolver {
           skipped: true,
           reason: "no-roadmap",
         });
-        return;
+        return false;
       }
 
       const roadmapContent = this.deps.readFileSync(roadmapPath, "utf-8");
@@ -683,6 +769,7 @@ export class WorktreeResolver {
         mode: "branch",
         result: "success",
       });
+      return true;
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       debugLog("WorktreeResolver", {