gsd-pi 2.76.0 → 2.77.0-dev.2daa994b6

package/dist/resources/extensions/gsd/safety/evidence-collector.js

@@ -3,9 +3,17 @@
  * Tracks every bash command, file write, and file edit during a unit execution.
  * Evidence is compared against LLM completion claims in evidence-cross-ref.ts.
  *
+ * Evidence is persisted to .gsd/safety/evidence-<mid>-<sid>-<tid>.json so it
+ * survives session restarts (pause/resume, crash recovery). On unit start,
+ * call resetEvidence() then loadEvidenceFromDisk(). On every new tool call,
+ * saveEvidenceToDisk() is called automatically by recordToolCall/recordToolResult.
+ *
  * Follows the same module-level Map pattern as auto-tool-tracking.ts.
  * Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
  */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync, } from "node:fs";
+import { join, dirname } from "node:path";
+import { randomBytes } from "node:crypto";
 // ─── Module State ───────────────────────────────────────────────────────────
 let unitEvidence = [];
 // ─── Public API ─────────────────────────────────────────────────────────────
@@ -27,6 +35,94 @@ export function getFilePaths() {
         .filter((e) => e.kind === "write" || e.kind === "edit")
         .map(e => e.path);
 }
+// ─── Persistence (Bug #4385 — evidence must survive session restarts) ────────
+/**
+ * Build the path for the evidence JSON file for a given unit.
+ * Lives under .gsd/safety/ which is gitignored and session-scoped.
+ */
+function evidencePath(basePath, milestoneId, sliceId, taskId) {
+    return join(basePath, ".gsd", "safety", `evidence-${milestoneId}-${sliceId}-${taskId}.json`);
+}
+/**
+ * Validate that a parsed value is an array of EvidenceEntry objects.
+ * Rejects corrupt / schema-mismatch data rather than letting it poison state.
+ */
+function isEvidenceArray(data) {
+    if (!Array.isArray(data))
+        return false;
+    return data.every((e) => {
+        if (e === null || typeof e !== "object")
+            return false;
+        const rec = e;
+        if (typeof rec.toolCallId !== "string")
+            return false;
+        if (typeof rec.timestamp !== "number")
+            return false;
+        if (rec.kind === "bash") {
+            return (typeof rec.command === "string" &&
+                typeof rec.exitCode === "number" &&
+                typeof rec.outputSnippet === "string");
+        }
+        if (rec.kind === "write" || rec.kind === "edit") {
+            return typeof rec.path === "string";
+        }
+        return false;
+    });
+}
+/**
+ * Persist the current in-memory evidence to disk so it survives a session
+ * restart. Called from saveEvidenceToDisk after recordToolCall/recordToolResult.
+ * Non-fatal — persistence failures must never break unit execution.
+ */
+export function saveEvidenceToDisk(basePath, milestoneId, sliceId, taskId) {
+    try {
+        const path = evidencePath(basePath, milestoneId, sliceId, taskId);
+        mkdirSync(dirname(path), { recursive: true });
+        const tmp = `${path}.tmp.${randomBytes(4).toString("hex")}`;
+        writeFileSync(tmp, JSON.stringify(unitEvidence, null, 2) + "\n", "utf-8");
+        renameSync(tmp, path);
+    }
+    catch {
+        // Non-fatal — don't let persistence failures break unit execution
+    }
+}
+/**
+ * Load persisted evidence from disk into the in-memory array.
+ * Call after resetEvidence() on session resume to restore context for a
+ * partially-executed unit. If the file does not exist (fresh unit), this
+ * is a no-op — getEvidence() will return [] which is correct.
+ */
+export function loadEvidenceFromDisk(basePath, milestoneId, sliceId, taskId) {
+    try {
+        const path = evidencePath(basePath, milestoneId, sliceId, taskId);
+        if (!existsSync(path))
+            return;
+        const raw = readFileSync(path, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (isEvidenceArray(parsed)) {
+            unitEvidence = parsed;
+        }
+    }
+    catch {
+        // Non-fatal — corrupt / missing file is treated as empty evidence
+    }
+}
+/**
+ * Delete the persisted evidence file for a unit after it has been fully
+ * processed. Prevents stale evidence from affecting future retries of
+ * the same unit ID.
+ */
+export function clearEvidenceFromDisk(basePath, milestoneId, sliceId, taskId) {
+    try {
+        const path = evidencePath(basePath, milestoneId, sliceId, taskId);
+        if (existsSync(path)) {
+            unlinkSync(path);
+        }
+    }
+    catch {
+        // Non-fatal
+    }
+}
 // ─── Recording (called from register-hooks.ts) ─────────────────────────────
 /**
  * Record a tool call at dispatch time (before execution).

package/dist/resources/extensions/gsd/safety/file-change-validator.js

@@ -4,13 +4,18 @@
  *
  * Uses tasks.expected_output (DB column, populated from per-task ## Expected Output)
  * and tasks.files (from slice PLAN.md - Files: subline) as the expected set.
- * Compares against git diff HEAD~1 --name-only after auto-commit.
+ * Compares against `git diff-tree --root --no-commit-id -r --name-only HEAD` after auto-commit.
+ * Using diff-tree --root handles initial commits, shallow clones, and merge commits correctly
+ * (Bug #4385 — git diff HEAD~1 failed on initial commits).
  *
  * Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
  */
+import { createRequire } from "node:module";
 import { execFileSync } from "node:child_process";
 import { normalizePlannedFileReference } from "../files.js";
 import { logWarning } from "../workflow-logger.js";
+const _require = createRequire(import.meta.url);
+const picomatch = _require("picomatch");
 // ─── Public API ─────────────────────────────────────────────────────────────
 /**
  * Validate file changes after auto-commit for an execute-task unit.
@@ -20,7 +25,7 @@ import { logWarning } from "../workflow-logger.js";
  * @param expectedOutput - JSON array from tasks.expected_output DB column
  * @param plannedFiles - JSON array from tasks.files DB column
  */
-export function validateFileChanges(basePath, expectedOutput, plannedFiles) {
+export function validateFileChanges(basePath, expectedOutput, plannedFiles, fileChangeAllowlist = []) {
     const allExpected = new Set([...expectedOutput, ...plannedFiles]);
     // If no expected files were planned, skip validation
     if (allExpected.size === 0)
@@ -33,8 +38,11 @@ export function validateFileChanges(basePath, expectedOutput, plannedFiles) {
     const projectFiles = actualFiles.filter(f => !f.startsWith(".gsd/") && !f.startsWith(".gsd\\"));
     // Normalize expected paths (strip leading ./ or /)
     const normalizedExpected = new Set([...allExpected].map((f) => normalizePlannedFileReference(f).replace(/^\.\//, "").replace(/^\//, "")));
-    // Compute symmetric difference
-    const unexpectedFiles = projectFiles.filter(f => !normalizedExpected.has(f));
+    // Build allowlist matchers once (dot: true so patterns like `**/.hidden` work).
+    const allowlistMatchers = fileChangeAllowlist.map(p => picomatch(p, { dot: true }));
+    const isAllowlisted = (f) => allowlistMatchers.some(m => m(f));
+    // Compute symmetric difference, excluding allowlisted files
+    const unexpectedFiles = projectFiles.filter(f => !normalizedExpected.has(f) && !isAllowlisted(f));
     const missingFiles = [...normalizedExpected].filter(f => !projectFiles.includes(f));
     const violations = [];
     for (const f of unexpectedFiles) {
@@ -62,7 +70,7 @@ export function validateFileChanges(basePath, expectedOutput, plannedFiles) {
 // ─── Internals ──────────────────────────────────────────────────────────────
 function getChangedFilesFromLastCommit(basePath) {
     try {
-        const result = execFileSync("git", ["diff", "--name-only", "HEAD~1", "HEAD"], { cwd: basePath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim();
+        const result = execFileSync("git", ["diff-tree", "--root", "--no-commit-id", "-r", "--name-only", "HEAD"], { cwd: basePath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim();
         return result ? result.split("\n").filter(Boolean) : [];
     }
     catch (e) {

package/dist/resources/extensions/gsd/safety/safety-harness.js

@@ -23,6 +23,7 @@ const DEFAULTS = {
     checkpoints: true,
     auto_rollback: false,
     timeout_scale_cap: 6,
+    file_change_allowlist: [],
 };
 // ─── Public API ─────────────────────────────────────────────────────────────
 /**
@@ -42,6 +43,9 @@ export function resolveSafetyHarnessConfig(raw) {
         checkpoints: typeof raw.checkpoints === "boolean" ? raw.checkpoints : DEFAULTS.checkpoints,
         auto_rollback: typeof raw.auto_rollback === "boolean" ? raw.auto_rollback : DEFAULTS.auto_rollback,
         timeout_scale_cap: typeof raw.timeout_scale_cap === "number" ? raw.timeout_scale_cap : DEFAULTS.timeout_scale_cap,
+        file_change_allowlist: Array.isArray(raw.file_change_allowlist)
+            ? raw.file_change_allowlist.filter((p) => typeof p === "string")
+            : DEFAULTS.file_change_allowlist,
     };
 }
 /**
@@ -56,7 +60,7 @@ export function isHarnessEnabled(raw) {
     return DEFAULTS.enabled;
 }
 // ─── Re-exports ─────────────────────────────────────────────────────────────
-export { resetEvidence, getEvidence, getBashEvidence, getFilePaths, recordToolCall, recordToolResult, } from "./evidence-collector.js";
+export { resetEvidence, getEvidence, getBashEvidence, getFilePaths, recordToolCall, recordToolResult, saveEvidenceToDisk, loadEvidenceFromDisk, clearEvidenceFromDisk, } from "./evidence-collector.js";
 export { classifyCommand } from "./destructive-guard.js";
 export { validateFileChanges } from "./file-change-validator.js";
 export { crossReferenceEvidence } from "./evidence-cross-ref.js";

package/dist/resources/extensions/gsd/service-tier.js

@@ -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.
  */
@@ -21,6 +21,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"];

package/dist/resources/extensions/gsd/skill-manifest.js

@@ -0,0 +1,168 @@
+// 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) {
+    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 = {
+    // 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) {
+    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(skills, unitType) {
+    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();
+export function warnIfManifestHasMissingSkills(unitType, installedNames) {
+    // 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/dist/resources/extensions/gsd/slice-cadence.js

@@ -0,0 +1,238 @@
+/**
+ * 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) {
+    return `milestone/${milestoneId}`;
+}
+function cleanupMergeArtifacts(projectRoot) {
+    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)}`);
+    }
+}
+/**
+ * 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, milestoneId, sliceId) {
+    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, milestoneId, startSha) {
+    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) {
+    return prefs?.git?.collapse_cadence ?? "milestone";
+}
+export function getMilestoneResquash(prefs) {
+    // Default true when cadence is slice — resquash preserves the milestone-
+    // level history shape users expect.
+    return prefs?.git?.milestone_resquash !== false;
+}