gsd-pi 2.77.0-dev.eaa4973bc → 2.78.0-dev.aeeb2ca00

package/src/resources/extensions/gsd/prompts/doctor-heal.md

@@ -7,9 +7,10 @@ Rules:
 2. Read before edit.
 3. Prefer fixing authoritative artifacts over masking warnings.
 4. For missing summaries or UAT files, generate the real artifact from existing slice/task context when possible — do not leave placeholders if you can reconstruct the real content.
-5. After each repair cluster, verify the relevant invariant directly from disk.
-6. When done, rerun `/gsd doctor {{doctorCommandSuffix}}` mentally by ensuring the remaining issue set for this scope is reduced or cleared.
-7. Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')` — use `gsd_milestone_status` to inspect DB state. Direct access bypasses the WAL connection owned by the engine and can corrupt in-flight writes.
+5. For a missing milestone `CONTEXT.md` when the milestone is already past `pre-planning` (phase is `executing`, `summarizing`, `validating-milestone`, or `completing-milestone`): the artifact was skipped during bootstrap and must be reconstructed before execution can resume. Read `PROJECT.md`, `REQUIREMENTS.md`, the milestone's `ROADMAP.md`, and any slice-level context on disk, then write `.gsd/milestones/<milestone-id>/<milestone-id>-CONTEXT.md` with the real context for the scoped milestone. Do not leave a stub — the plan gate will reject it on the next cycle.
+6. After each repair cluster, verify the relevant invariant directly from disk.
+7. When done, rerun `/gsd doctor {{doctorCommandSuffix}}` mentally by ensuring the remaining issue set for this scope is reduced or cleared.
+8. Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')` — use `gsd_milestone_status` to inspect DB state. Direct access bypasses the WAL connection owned by the engine and can corrupt in-flight writes.
 
 ## Doctor Summary
 
@@ -27,4 +28,4 @@ Then:
 - Repair the unresolved issues in scope
 - Keep changes minimal and targeted
 - If unresolved issues remain outside scope, leave them untouched and mention them briefly
-- End with: "GSD doctor heal complete."
+- End with: "GSD doctor heal complete."

package/src/resources/extensions/gsd/prompts/plan-slice.md

@@ -20,9 +20,22 @@ Pay particular attention to **Forward Intelligence** sections — they contain h
 
 You have full tool access. Before decomposing, explore the relevant code to ground your plan in reality.
 
-### Verify Roadmap Assumptions
+### Verify Roadmap Assumptions (JIT Reassessment — ADR-003 §4)
 
-Check prior slice summaries (inlined above as dependency summaries, if present). If prior slices discovered constraints, changed approaches, or flagged fragility, adjust your plan accordingly. The roadmap description may be stale — verify it against the current codebase state.
+Before planning this slice, verify that the roadmap's assumptions still hold given prior slice summaries. Check inlined dependency summaries (below) for discovered constraints, changed approaches, or flagged fragility.
+
+**If the remaining roadmap needs adjustment, modify it before proceeding:**
+
+- If a downstream slice's title/demo/dependencies are now wrong, call `gsd_reassess_roadmap` with the corrected `sliceChanges.modified` entry.
+- If new work surfaced that deserves its own slice, add it via `sliceChanges.added`.
+- If a downstream slice is now redundant or out of scope, remove it via `sliceChanges.removed`.
+- **Bias strongly toward "roadmap is fine."** Most slice completions produce no structural change. Only adjust when there is concrete evidence a downstream slice is wrong — not speculative concern. Over-reassessment is costlier than a later mid-slice replan.
+
+Completed slices are immutable: never modify or remove a slice whose status is complete.
+
+Then proceed with planning this slice against the (possibly updated) roadmap.
+
+The roadmap description may be stale — verify it against the current codebase state.
 
 ### Explore Slice Scope
 

package/src/resources/extensions/gsd/safety/git-checkpoint.ts

@@ -72,6 +72,21 @@ export function rollbackToCheckpoint(
       return false;
     }
 
+    // Preserve any staged or untracked user work before the hard reset.
+    // The user may have a partial fix staged that they wanted to inspect;
+    // reset --hard wipes both staged and unstaged changes (reflog only
+    // covers committed state). Push a labeled stash first so recovery
+    // is possible. (Issue #4980 HIGH-4)
+    try {
+      execFileSync(
+        "git",
+        ["stash", "push", "--include-untracked", "-m", `gsd: pre-rollback-stash ${unitId} ${new Date().toISOString()}`],
+        { cwd: basePath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" },
+      );
+    } catch {
+      /* nothing to stash, or stash refused — proceed with reset */
+    }
+
     // Reset branch pointer and working tree to checkpoint SHA in one step.
     // Using `git reset --hard <sha>` works on the currently checked-out branch
     // (unlike `git branch -f` which is rejected for checked-out branches).

package/src/resources/extensions/gsd/service-tier.ts

@@ -2,8 +2,8 @@
  * Service Tier — gating, status formatting, icon resolution, and
  * the /gsd fast command handler.
  *
- * Service tiers (priority/flex) are an OpenAI feature that only applies
- * to gpt-5.4 variants. This module centralizes the model-gating logic
+ * Service tiers (priority/flex) are an OpenAI feature that currently only
+ * applies to gpt-5.4 variants in GSD. This module centralizes the model-gating logic
  * so that icons, preferences, and the before_provider_request hook all
  * use a single source of truth.
  */
@@ -35,6 +35,9 @@ const SERVICE_TIER_SCOPE_NOTE = "Only affects gpt-5.4 models, regardless of prov
  * (set via CAPABILITY_PATCHES in packages/pi-ai/src/models.ts). When callers
  * have access to the full Model object, prefer reading capabilities directly.
  *
+ * GPT-5.5 is intentionally excluded until we verify its provider payload
+ * contract instead of assuming `service_tier` support.
+ *
  * See: https://github.com/gsd-build/gsd-2/issues/2546
  */
 const SERVICE_TIER_MODEL_PREFIXES = ["gpt-5.4"] as const;

package/src/resources/extensions/gsd/session-lock.ts

@@ -188,13 +188,14 @@ function ensureExitHandler(_gsdDir: string): void {
     // Lock files accumulate across main project .gsd/, worktree .gsd/,
     // and projects registry paths — cleanup must cover all of them.
     for (const dir of _lockDirRegistry) {
+      const lockFile = join(dir, LOCK_FILE);
+      const ownsRegisteredLock = isLockFileOwnedByCurrentProcess(lockFile);
       try {
-        const lockFile = join(dir, LOCK_FILE);
-        if (existsSync(lockFile)) unlinkSync(lockFile);
+        if (ownsRegisteredLock && existsSync(lockFile)) unlinkSync(lockFile);
       } catch { /* best-effort */ }
       try {
         const lockDir = join(dir + ".lock");
-        if (existsSync(lockDir)) rmSync(lockDir, { recursive: true, force: true });
+        if (ownsRegisteredLock && existsSync(lockDir)) rmSync(lockDir, { recursive: true, force: true });
       } catch { /* best-effort */ }
     }
   });
@@ -526,10 +527,13 @@ export function releaseSessionLock(basePath: string): void {
     _releaseFunction = null;
   }
 
-  // Remove the lock file at the current path
+  // Remove the lock file at the current path only if it still belongs to us.
+  // Lost-lock cleanup can run after another process has taken ownership; in
+  // that case deleting auto.lock would erase the newer owner's evidence.
   const lp = lockPath(basePath);
+  const ownsPrimaryLock = isLockFileOwnedByCurrentProcess(lp);
   try {
-    if (existsSync(lp)) unlinkSync(lp);
+    if (ownsPrimaryLock && existsSync(lp)) unlinkSync(lp);
   } catch {
     // Non-fatal
   }
@@ -540,12 +544,12 @@ export function releaseSessionLock(basePath: string): void {
   const lockTarget = effectiveLockTarget(gsdDir);
   try {
     const lockDir = join(lockTarget + ".lock");
-    if (existsSync(lockDir)) rmSync(lockDir, { recursive: true, force: true });
+    if (ownsPrimaryLock && existsSync(lockDir)) rmSync(lockDir, { recursive: true, force: true });
   } catch {
     // Non-fatal
   }
   // Also clean the per-milestone parallel directory itself if it exists
-  if (lockTarget !== gsdDir) {
+  if (ownsPrimaryLock && lockTarget !== gsdDir) {
     try {
       if (existsSync(lockTarget)) rmSync(lockTarget, { recursive: true, force: true });
     } catch {
@@ -556,13 +560,14 @@ export function releaseSessionLock(basePath: string): void {
   // Clean ALL registered lock paths (#1578) — lock files accumulate across
   // main project .gsd/, worktree .gsd/, and projects registry paths.
   for (const dir of _lockDirRegistry) {
+    const lockFile = join(dir, LOCK_FILE);
+    const ownsRegisteredLock = isLockFileOwnedByCurrentProcess(lockFile);
     try {
-      const lockFile = join(dir, LOCK_FILE);
-      if (existsSync(lockFile)) unlinkSync(lockFile);
+      if (ownsRegisteredLock && existsSync(lockFile)) unlinkSync(lockFile);
     } catch { /* best-effort */ }
     try {
       const lockDir = join(dir + ".lock");
-      if (existsSync(lockDir)) rmSync(lockDir, { recursive: true, force: true });
+      if (ownsRegisteredLock && existsSync(lockDir)) rmSync(lockDir, { recursive: true, force: true });
     } catch { /* best-effort */ }
   }
   _lockDirRegistry.clear();
@@ -619,6 +624,11 @@ function readExistingLockData(lp: string): SessionLockData | null {
   }
 }
 
+function isLockFileOwnedByCurrentProcess(lp: string): boolean {
+  const existing = readExistingLockData(lp);
+  return existing?.pid === process.pid;
+}
+
 /**
  * Retry-tolerant variant of readExistingLockData for use in onCompromised and
  * other paths where a transient filesystem hiccup (NFS/CIFS latency, macOS APFS

package/src/resources/extensions/gsd/skill-manifest.ts

@@ -0,0 +1,175 @@
+// GSD2 + skill-manifest — per-unit-type skill allowlist resolver (RFC #4779)
+//
+// Each auto-mode unit type can declare which skills are relevant to it. This
+// trims the set of skills considered for activation in the per-unit prompt,
+// reducing prompt token bloat and sharpening model focus.
+//
+// Contract:
+//   - Unknown unit types fall through to "all skills" (current behavior).
+//   - A manifest entry referencing a skill that is not installed is a silent
+//     no-op at filter time — the filter passes through installed skills only.
+//   - The allowlist is an inclusion list: only skills whose normalized name
+//     appears in the allowlist are retained. Order is not preserved.
+//
+// Phase 1 scope: seed manifests for a small number of unit types as proof.
+// Additional unit types can be added incrementally; each addition is a pure
+// data change with no wiring cost.
+
+import { logWarning } from "./workflow-logger.js";
+
+/** Normalize a skill reference the same way callers do (lowercase, trim). */
+function normalize(name: string): string {
+  return name.trim().toLowerCase();
+}
+
+/**
+ * Allowlist per unit type. Keys match unit type identifiers used by auto-mode
+ * dispatch. Values are normalized skill names.
+ *
+ * Wildcard semantics: a unit type absent from this map resolves to `null`
+ * (wildcard) — meaning "all installed skills are eligible". Prefer absence
+ * over an exhaustive list when uncertain.
+ */
+const UNIT_TYPE_SKILL_MANIFEST: Record<string, string[]> = {
+  // Milestone-level planning / meta flows — predictable skill sets.
+  "research-milestone": [
+    "write-docs",
+    "write-milestone-brief",
+    "decompose-into-slices",
+    "grill-me",
+    "design-an-interface",
+    "api-design",
+    "observability",
+  ],
+  "plan-milestone": [
+    "write-milestone-brief",
+    "decompose-into-slices",
+    "design-an-interface",
+    "grill-me",
+    "write-docs",
+    "api-design",
+    "tdd",
+    "verify-before-complete",
+  ],
+  "complete-milestone": [
+    "verify-before-complete",
+    "write-docs",
+    "handoff",
+    "forensics",
+    "observability",
+    "security-review",
+  ],
+  "validate-milestone": [
+    "verify-before-complete",
+    "review",
+    "test",
+    "lint",
+    "security-review",
+    "accessibility",
+    "forensics",
+    "observability",
+  ],
+  "reassess-roadmap": [
+    "decompose-into-slices",
+    "grill-me",
+    "write-milestone-brief",
+    "write-docs",
+    "forensics",
+  ],
+  // Slice-level research / planning.
+  "research-slice": [
+    "write-docs",
+    "decompose-into-slices",
+    "design-an-interface",
+    "grill-me",
+    "api-design",
+    "observability",
+  ],
+  "plan-slice": [
+    "decompose-into-slices",
+    "design-an-interface",
+    "grill-me",
+    "write-docs",
+    "api-design",
+    "tdd",
+    "verify-before-complete",
+  ],
+  "refine-slice": [
+    "decompose-into-slices",
+    "design-an-interface",
+    "grill-me",
+    "write-docs",
+    "api-design",
+    "tdd",
+    "verify-before-complete",
+  ],
+  "replan-slice": [
+    "decompose-into-slices",
+    "grill-me",
+    "design-an-interface",
+    "write-docs",
+    "api-design",
+  ],
+  "run-uat": [
+    "verify-before-complete",
+    "test",
+    "review",
+    "accessibility",
+  ],
+  // `execute-task` intentionally omitted — implementation hot path covers a
+  // wide surface of technologies; wildcard fallback preserves today's
+  // behavior until per-task skill hints can be derived from task-plan
+  // frontmatter. See RFC #4779.
+};
+
+/**
+ * Resolve the skill allowlist for a unit type.
+ *
+ * @returns Array of normalized skill names when an entry exists, or `null`
+ *   when the unit type is unknown (wildcard — caller should not filter).
+ */
+export function resolveSkillManifest(unitType: string | undefined): string[] | null {
+  if (!unitType) return null;
+  const entry = UNIT_TYPE_SKILL_MANIFEST[unitType];
+  if (!entry) return null;
+  return entry.map(normalize);
+}
+
+/**
+ * Filter a skill list by the manifest for `unitType`. Pass-through when the
+ * manifest is wildcard (unknown unit type) or `unitType` is undefined.
+ */
+export function filterSkillsByManifest<T extends { name: string }>(
+  skills: T[],
+  unitType: string | undefined,
+): T[] {
+  const allowlist = resolveSkillManifest(unitType);
+  if (allowlist === null) return skills;
+  const allowed = new Set(allowlist);
+  return skills.filter(skill => allowed.has(normalize(skill.name)));
+}
+
+/**
+ * Dev-mode guard: warn once per process if a manifest entry references a name
+ * that is not currently installed. Silent in production.
+ */
+const warnedMissing = new Set<string>();
+
+export function warnIfManifestHasMissingSkills(
+  unitType: string | undefined,
+  installedNames: Set<string>,
+): void {
+  // Strict mode is intentionally opt-in via exactly "1"; values like "0" or
+  // "false" must preserve the normal silent manifest behavior.
+  if (process.env.GSD_SKILL_MANIFEST_STRICT !== "1") return;
+  const allowlist = resolveSkillManifest(unitType);
+  if (!allowlist) return;
+  for (const name of allowlist) {
+    const key = `${unitType}:${name}`;
+    if (warnedMissing.has(key)) continue;
+    if (!installedNames.has(name)) {
+      warnedMissing.add(key);
+      logWarning("prompt", `skill-manifest: references uninstalled skill '${name}' for unit '${unitType}'`);
+    }
+  }
+}

package/src/resources/extensions/gsd/slice-cadence.ts

@@ -0,0 +1,299 @@
+/**
+ * Slice-cadence collapse — #4765.
+ *
+ * When `git.collapse_cadence: "slice"` is set, each slice's commits are
+ * squash-merged from the milestone branch to main as soon as the slice
+ * passes validation. Shrinks the orphan window (#4761) from milestone-size
+ * to slice-size and surfaces merge conflicts per-slice rather than all at
+ * once at milestone end.
+ *
+ * This module is deliberately focused and narrower than mergeMilestoneToMain:
+ *   - No worktree teardown (worktree is reused for the next slice)
+ *   - No DB reconciliation (modern worktrees share the main DB via path resolver)
+ *   - No roadmap/summary/gate handling (that's still the milestone's job)
+ *   - Fails loudly on dirty main — caller is responsible for cleanliness
+ *
+ * Kernighan: the v1 surface handles the happy path + conflict. Edge cases
+ * that mergeMilestoneToMain covers (concurrent merges, shared DB paths,
+ * submodules) are explicit non-goals; users opt in via preference and early-
+ * adopter scenarios are scoped narrow.
+ */
+
+import { existsSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+
+import { GSDError, GSD_GIT_ERROR } from "./errors.js";
+import { MergeConflictError } from "./git-service.js";
+import {
+  nativeBranchForceReset,
+  nativeCheckoutBranch,
+  nativeCommit,
+  nativeCommitCountBetween,
+  nativeConflictFiles,
+  nativeDetectMainBranch,
+  nativeMergeSquash,
+} from "./native-git-bridge.js";
+import { resolveGitDir } from "./worktree-manager.js";
+import { logWarning } from "./workflow-logger.js";
+import { emitSliceMerged, emitMilestoneResquash } from "./worktree-telemetry.js";
+
+/**
+ * Auto-worktree milestone branch name. Must match autoWorktreeBranch() in
+ * auto-worktree.ts; duplicated here to avoid a cyclic import.
+ */
+function milestoneBranchName(milestoneId: string): string {
+  return `milestone/${milestoneId}`;
+}
+
+function cleanupMergeArtifacts(projectRoot: string): void {
+  try {
+    const gitDir = resolveGitDir(projectRoot);
+    for (const f of ["SQUASH_MSG", "MERGE_MSG", "MERGE_HEAD"]) {
+      const p = join(gitDir, f);
+      if (existsSync(p)) unlinkSync(p);
+    }
+  } catch (err) {
+    logWarning("worktree", `merge artifact cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+export interface SliceMergeResult {
+  commitSha: string | null;
+  mainBranch: string;
+  milestoneBranch: string;
+  durationMs: number;
+  skipped: boolean;
+  skippedReason?: string;
+}
+
+/**
+ * Squash-merge one slice's commits from the milestone branch to main.
+ *
+ * Preconditions:
+ *   - Caller is on the milestone branch inside the worktree
+ *   - `projectRoot` points at the real project root (not the worktree)
+ *
+ * Post-conditions on success:
+ *   - Slice's commits are a single squash commit on main
+ *   - `milestone/<MID>` is fast-forwarded to main (so next slice's work
+ *     starts from a clean base)
+ *   - caller's process.cwd is restored
+ *
+ * Throws MergeConflictError on conflicts; caller should surface and stop.
+ * Throws GSDError on dirty main / detection failures.
+ */
+export function mergeSliceToMain(
+  projectRoot: string,
+  milestoneId: string,
+  sliceId: string,
+): SliceMergeResult {
+  const started = Date.now();
+  const worktreeCwd = process.cwd();
+  const milestoneBranch = milestoneBranchName(milestoneId);
+  const mainBranch = nativeDetectMainBranch(projectRoot);
+
+  // Fast path: if the milestone branch has no commits ahead of main, there
+  // is nothing to merge. Return a skip result instead of no-op'ing silently
+  // so the caller's telemetry shows the decision.
+  let commitsAhead = 0;
+  try {
+    commitsAhead = nativeCommitCountBetween(projectRoot, mainBranch, milestoneBranch);
+  } catch {
+    // If we can't count, assume there's work and let the merge proceed —
+    // a failing merge is more informative than a silent skip.
+    commitsAhead = 1;
+  }
+  if (commitsAhead === 0) {
+    // Do NOT emit slice-merged here — this is a no-op, not a merge. Emitting
+    // would inflate slicesMerged in telemetry/forensics and distort the
+    // conflict rate denominator.
+    return {
+      commitSha: null,
+      mainBranch,
+      milestoneBranch,
+      durationMs: Date.now() - started,
+      skipped: true,
+      skippedReason: "no-commits-ahead",
+    };
+  }
+
+  process.chdir(projectRoot);
+  try {
+    // Dirty-main check — v1 fails loudly rather than auto-stashing. Users
+    // running slice-cadence opt in knowing main stays clean between merges.
+    const status = execFileSync("git", ["status", "--porcelain"], {
+      cwd: projectRoot,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+    }).trim();
+    if (status) {
+      throw new GSDError(
+        GSD_GIT_ERROR,
+        `slice-cadence merge requires a clean project root; uncommitted changes detected. ` +
+        `Commit or stash at ${projectRoot} before retrying. Status:\n${status}`,
+      );
+    }
+
+    nativeCheckoutBranch(projectRoot, mainBranch);
+
+    // Clean any stale merge artifacts before attempting the squash (#2912 pattern)
+    cleanupMergeArtifacts(projectRoot);
+
+    const mergeResult = nativeMergeSquash(projectRoot, milestoneBranch);
+    if (!mergeResult.success) {
+      const conflictedFiles = mergeResult.conflicts.length > 0
+        ? mergeResult.conflicts
+        : nativeConflictFiles(projectRoot);
+      cleanupMergeArtifacts(projectRoot);
+      try {
+        emitSliceMerged(projectRoot, milestoneId, sliceId, {
+          durationMs: Date.now() - started,
+          conflict: true,
+        });
+      } catch { /* silent */ }
+      throw new MergeConflictError(
+        conflictedFiles,
+        "squash",
+        milestoneBranch,
+        mainBranch,
+      );
+    }
+
+    // Commit the squash with a slice-scoped message
+    const commitSha = nativeCommit(
+      projectRoot,
+      `gsd: merge ${sliceId} of ${milestoneId} (slice-cadence)`,
+    );
+
+    // Advance the milestone branch to main so the next slice's commits start
+    // from a clean base. Force-reset is safe because we just merged this
+    // branch's entire delta.
+    nativeBranchForceReset(projectRoot, milestoneBranch, mainBranch);
+
+    const durationMs = Date.now() - started;
+    try {
+      emitSliceMerged(projectRoot, milestoneId, sliceId, {
+        durationMs,
+        conflict: false,
+        commitSha: commitSha ?? undefined,
+      });
+    } catch { /* silent */ }
+
+    return {
+      commitSha,
+      mainBranch,
+      milestoneBranch,
+      durationMs,
+      skipped: false,
+    };
+  } finally {
+    // Always restore cwd even if anything above threw.
+    try { process.chdir(worktreeCwd); } catch { /* best-effort */ }
+  }
+}
+
+/**
+ * Re-squash per-slice commits on main into a single milestone commit.
+ *
+ * Runs at milestone completion when `collapse_cadence: "slice"` AND
+ * `milestone_resquash: true`. The `startSha` is the SHA of main immediately
+ * before the milestone's first slice merge — the caller is responsible for
+ * recording this (AutoSession field, git ref, or DB row).
+ *
+ * Strategy: soft-reset main to startSha, then commit the net diff. The
+ * N slice commits between startSha and HEAD are collapsed into one.
+ *
+ * No-op (returns false) if startSha equals HEAD (nothing to re-squash).
+ */
+export function resquashMilestoneOnMain(
+  projectRoot: string,
+  milestoneId: string,
+  startSha: string,
+): { resquashed: boolean; newSha: string | null } {
+  const mainBranch = nativeDetectMainBranch(projectRoot);
+  const worktreeCwd = process.cwd();
+
+  process.chdir(projectRoot);
+  try {
+    nativeCheckoutBranch(projectRoot, mainBranch);
+
+    // Verify the startSha..HEAD range contains ONLY this milestone's slice-
+    // cadence commits. If any unrelated commits landed on main since the
+    // milestone started (e.g. concurrent work, cherry-picks, hotfixes), a
+    // blind `git reset --soft` would fold them into the re-squash and rewrite
+    // their attribution. Fail closed — the user can resolve manually.
+    const expectedSuffix = `(slice-cadence)`;
+    const expectedMilestoneToken = ` of ${milestoneId} `;
+    let subjectsRaw = "";
+    try {
+      subjectsRaw = execFileSync(
+        "git",
+        ["log", "--format=%s", `${startSha}..HEAD`],
+        { cwd: projectRoot, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" },
+      );
+    } catch {
+      return { resquashed: false, newSha: null };
+    }
+    const subjects = subjectsRaw.split("\n").filter((s) => s.length > 0);
+    const sliceCount = subjects.length;
+    if (sliceCount === 0) {
+      return { resquashed: false, newSha: null };
+    }
+    const foreign = subjects.filter(
+      (s) => !(s.endsWith(expectedSuffix) && s.includes(expectedMilestoneToken)),
+    );
+    if (foreign.length > 0) {
+      logWarning(
+        "worktree",
+        `slice-cadence: skipping milestone resquash for ${milestoneId} — ` +
+        `${foreign.length} non-slice-cadence commit(s) in ${startSha}..HEAD ` +
+        `would be folded in. First: "${foreign[0]}". Resolve history manually.`,
+      );
+      return { resquashed: false, newSha: null };
+    }
+
+    // Safe to collapse: all commits in the range are this milestone's slices.
+    execFileSync("git", ["reset", "--soft", startSha], {
+      cwd: projectRoot,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+    });
+
+    const newSha = nativeCommit(
+      projectRoot,
+      `gsd: complete milestone ${milestoneId} (${sliceCount} slices re-squashed)`,
+      { allowEmpty: true },
+    );
+
+    try {
+      emitMilestoneResquash(projectRoot, milestoneId, {
+        sliceCount,
+        startSha,
+        endSha: newSha ?? undefined,
+      });
+    } catch { /* silent */ }
+
+    return { resquashed: true, newSha };
+  } finally {
+    try { process.chdir(worktreeCwd); } catch { /* best-effort */ }
+  }
+}
+
+/**
+ * Read the effective collapse cadence from validated preferences. Accepts
+ * a raw preferences object (the shape loadEffectiveGSDPreferences returns).
+ */
+export function getCollapseCadence(
+  prefs: { git?: { collapse_cadence?: "milestone" | "slice" } } | undefined | null,
+): "milestone" | "slice" {
+  return prefs?.git?.collapse_cadence ?? "milestone";
+}
+
+export function getMilestoneResquash(
+  prefs: { git?: { milestone_resquash?: boolean } } | undefined | null,
+): boolean {
+  // Default true when cadence is slice — resquash preserves the milestone-
+  // level history shape users expect.
+  return prefs?.git?.milestone_resquash !== false;
+}