gsd-pi 2.77.0-dev.1d17f366c → 2.77.0-dev.2daa994b6

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;
+}

package/dist/resources/extensions/gsd/tools/validate-milestone.js

@@ -11,6 +11,7 @@
 import { join } from "node:path";
 import { transaction, insertAssessment, deleteAssessmentByScope, getMilestoneSlices, } from "../gsd-db.js";
 import { resolveMilestonePath, clearPathCache } from "../paths.js";
+import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
 import { VALIDATION_VERDICTS, isValidMilestoneVerdict } from "../verdict-parser.js";
@@ -59,14 +60,18 @@ export async function handleValidateMilestone(params, basePath, opts) {
         return { error: `verdict must be one of: ${VALIDATION_VERDICTS.join(", ")}` };
     }
     // ── Resolve paths and render markdown ────────────────────────────────
+    // #4761: route through the canonical-root resolver so that when a live
+    // worktree exists for this milestone, validation reads/writes the
+    // worktree's artifacts instead of stale project-root state.
     const validationMd = renderValidationMarkdown(params);
+    const canonicalBase = resolveCanonicalMilestoneRoot(basePath, params.milestoneId);
     let validationPath;
-    const milestoneDir = resolveMilestonePath(basePath, params.milestoneId);
+    const milestoneDir = resolveMilestonePath(canonicalBase, params.milestoneId);
     if (milestoneDir) {
         validationPath = join(milestoneDir, `${params.milestoneId}-VALIDATION.md`);
     }
     else {
-        const gsdDir = join(basePath, ".gsd");
+        const gsdDir = join(canonicalBase, ".gsd");
         const manualDir = join(gsdDir, "milestones", params.milestoneId);
         validationPath = join(manualDir, `${params.milestoneId}-VALIDATION.md`);
     }

package/dist/resources/extensions/gsd/unit-context-composer.js

@@ -0,0 +1,147 @@
+// GSD-2 — UnitContextComposer (#4782 phase 2).
+//
+// Reads a unit type's manifest and orchestrates artifact inlining through
+// a caller-provided resolver. Returns a joined context block suitable for
+// substitution into the unit's prompt template.
+//
+// Design rationale:
+//   - Pure dependency on the manifest module — no circular import with
+//     `auto-prompts.ts` where the per-artifact-key resolver lives.
+//   - Caller-supplied resolver means the composer can be unit-tested with
+//     trivial mocks; production wiring in `auto-prompts.ts` dispatches to
+//     the existing `inlineFile` / `inline*FromDb` helpers.
+//   - Null-returning resolvers are skipped silently: they model the
+//     "artifact is optional / missing / not applicable to this milestone"
+//     case. The composer never errors on a missing artifact.
+//
+// Scope: phase 2 pilot shipped `composeInlinedContext` for static-key
+// inlining. Phase 3.5 (#4924) adds the v2 surface — `composeUnitContext`
+// — which also handles excerpts, computed artifacts, and prepended blocks.
+// `composeInlinedContext` stays for backward compatibility with the
+// already-migrated simple builders.
+//
+// ─── Composer boundary invariant (#4924) ─────────────────────────────────
+//
+// The composer is allowed to:
+//   - order named sections per the manifest's declared sequence
+//   - resolve registered artifacts (static / computed / excerpt / on-demand)
+//   - apply typed policies (knowledge / memory / codebase-map / preferences)
+//
+// The composer must NOT grow:
+//   - arbitrary conditionals on unit state
+//   - loops over caller-supplied data
+//   - string templating beyond section composition (join + separator)
+//
+// Logic that needs those belongs in a typed computed-artifact builder
+// owned by the unit, not in the composer. Reviews must enforce this — it
+// is the difference between an orchestrator and a runaway DSL.
+import { resolveManifest, } from "./unit-context-manifest.js";
+/**
+ * Produce the inlined-context portion of a unit's system prompt by
+ * walking the manifest's `artifacts.inline` list in order and calling
+ * the provided resolver for each key.
+ *
+ * Returns an empty string when the unit type has no manifest registered,
+ * so callers can guard their wiring with a simple truthy check. Unknown
+ * unit types do not error — this mirrors `resolveManifest`'s contract.
+ *
+ * The separator between inlined blocks matches the in-tree convention
+ * (`\n\n---\n\n`) so composer output slots into existing prompt templates
+ * without visible diff.
+ */
+export async function composeInlinedContext(unitType, resolveArtifact) {
+    const manifest = resolveManifest(unitType);
+    if (!manifest)
+        return "";
+    const blocks = [];
+    for (const key of manifest.artifacts.inline) {
+        const body = await resolveArtifact(key);
+        if (body !== null && body.length > 0) {
+            blocks.push(body);
+        }
+    }
+    return blocks.join("\n\n---\n\n");
+}
+/**
+ * Convenience helper returning the manifest's declared budget so callers
+ * can telemetry a mismatch between actual prompt size and declared budget.
+ * Returns null for unknown unit types.
+ */
+export function manifestBudgetChars(unitType) {
+    const manifest = resolveManifest(unitType);
+    return manifest ? manifest.maxSystemPromptChars : null;
+}
+const SECTION_SEPARATOR = "\n\n---\n\n";
+/**
+ * Compose all manifest-declared context for a unit type using the v2
+ * surface. Walks `prepend` first (computed-only), then the `inline` list
+ * (static keys via `resolveArtifact`), then `excerpt` (via `resolveExcerpt`),
+ * then `artifacts.computed` (via the typed registry). Order within each
+ * section follows the manifest's declared sequence.
+ *
+ * Unknown unit types return empty strings for both sections — callers can
+ * fall back to existing imperative wiring without a special case.
+ *
+ * Resolver / registry omissions: if the manifest declares an entry but no
+ * resolver / registry entry is provided, the composer skips it silently.
+ * This matches the v1 contract where a null body is a no-op, and lets
+ * partial migrations land without forcing every consumer to register
+ * every artifact class up-front.
+ */
+export async function composeUnitContext(unitType, opts) {
+    const manifest = resolveManifest(unitType);
+    if (!manifest)
+        return { prepend: "", inline: "" };
+    // Single-source `unitType`: the manifest is resolved against the
+    // function arg, but computed builders read it from `base.unitType`.
+    // If those ever diverge (caller passes one type to composeUnitContext
+    // but a different one in opts.base), the composer would silently
+    // mix one unit's manifest with another unit's computed context.
+    // Normalize here so the composer dispatches a consistent identity
+    // through to every builder.
+    const normalizedOpts = {
+        ...opts,
+        base: { ...opts.base, unitType },
+    };
+    const prependBlocks = await runComputed(manifest.prepend ?? [], normalizedOpts);
+    const inlineBlocks = [];
+    for (const key of manifest.artifacts.inline) {
+        if (!normalizedOpts.resolveArtifact)
+            break;
+        const body = await normalizedOpts.resolveArtifact(key);
+        if (body && body.length > 0)
+            inlineBlocks.push(body);
+    }
+    for (const key of manifest.artifacts.excerpt) {
+        if (!normalizedOpts.resolveExcerpt)
+            break;
+        const body = await normalizedOpts.resolveExcerpt(key);
+        if (body && body.length > 0)
+            inlineBlocks.push(body);
+    }
+    inlineBlocks.push(...await runComputed(manifest.artifacts.computed ?? [], normalizedOpts));
+    return {
+        prepend: prependBlocks.join(SECTION_SEPARATOR),
+        inline: inlineBlocks.join(SECTION_SEPARATOR),
+    };
+}
+/**
+ * Invoke the registered builder for each declared computed id, in order.
+ * Missing registry entries (manifest declares the id but caller didn't
+ * register it) are skipped silently — see composeUnitContext rationale.
+ */
+async function runComputed(ids, opts) {
+    if (ids.length === 0 || !opts.computed)
+        return [];
+    const registry = opts.computed;
+    const out = [];
+    for (const id of ids) {
+        const entry = registry[id];
+        if (!entry)
+            continue;
+        const body = await entry.build(entry.inputs, opts.base);
+        if (body && body.length > 0)
+            out.push(body);
+    }
+    return out;
+}