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

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

@@ -0,0 +1,334 @@
+// GSD-2 — UnitContextManifest (#4782 phase 1).
+//
+// Declarative description of what context each auto-mode unit type needs
+// in its system prompt. Establishes the contract that later phases will
+// use to drive a single composeSystemPromptForUnit() — replacing the
+// per-unit-type branching currently spread across `auto-prompts.ts`.
+//
+// **Phase 1 ships the type + the data + a CI coverage guard.** It adds
+// zero wiring — no caller reads a manifest yet. Every unit type gets a
+// manifest that describes today's behavior as faithfully as possible, so
+// when the composer lands in phase 2 the migration can proceed manifest-
+// by-manifest without behavior change.
+//
+// Phased rollout tracking:
+//   - Phase 1 (this PR): schema + manifests + coverage test.
+//   - Phase 2: add composeSystemPromptForUnit(); migrate one low-risk
+//     unit type (e.g. reassess-roadmap) as the pilot.
+//   - Phase 3: migrate remaining unit types, tighten manifests per
+//     empirical usage, introduce skipWhen predicates absorbing the
+//     reassess opt-in gate from #4778.
+//   - Phase 4: introduce pipeline variants as declared sequences,
+//     absorbing the scope-classifier gates from #4781.
+//
+// Naming:
+//   - Artifact keys are STABLE strings (not paths). Path resolution is
+//     the composer's job; manifests describe intent, not disk layout.
+//   - Char budgets are nominal — blown budgets log a telemetry event,
+//     they do not truncate or error (the composer decides fallback).
+// ─── Artifact registry ────────────────────────────────────────────────────
+/**
+ * Stable identifiers for every artifact class a unit might inline, excerpt,
+ * or reference on-demand. Adding a new artifact class requires (a) a key
+ * here, (b) path/body resolution in the composer, and (c) updates to any
+ * manifest that should surface it.
+ */
+export const ARTIFACT_KEYS = [
+    // Milestone-scoped
+    "roadmap",
+    "milestone-context",
+    "milestone-summary",
+    "milestone-validation",
+    "milestone-research",
+    "milestone-plan",
+    // Slice-scoped
+    "slice-context",
+    "slice-research",
+    "slice-plan",
+    "slice-summary",
+    "slice-uat",
+    "slice-assessment",
+    // Task-scoped
+    "task-plan",
+    "task-summary",
+    "prior-task-summaries",
+    "dependency-summaries",
+    // Project-scoped
+    "requirements",
+    "decisions",
+    "project",
+    "templates",
+];
+// ─── Manifests ────────────────────────────────────────────────────────────
+// Phase 1 policy: every manifest encodes today's behavior. Skills = "all"
+// unless the unit type was already narrowed via the existing skill-manifest
+// resolver (#4779). Memory/knowledge policies reflect the defaults in
+// `bootstrap/system-context.ts`. Artifact classifications follow what
+// `auto-prompts.ts` inlines today for each unit type.
+const COMMON_BUDGET_LARGE = 1_500_000; // ~400K tokens
+const COMMON_BUDGET_MEDIUM = 750_000; // ~200K tokens
+const COMMON_BUDGET_SMALL = 250_000; // ~65K tokens
+/**
+ * Canonical unit types handled by auto-mode dispatch. The coverage test
+ * enumerates these against `UNIT_MANIFESTS` to catch manifest drift when
+ * a new unit type lands.
+ */
+export const KNOWN_UNIT_TYPES = [
+    "research-milestone",
+    "plan-milestone",
+    "discuss-milestone",
+    "validate-milestone",
+    "complete-milestone",
+    "research-slice",
+    "plan-slice",
+    "refine-slice",
+    "replan-slice",
+    "complete-slice",
+    "reassess-roadmap",
+    "execute-task",
+    "reactive-execute",
+    "run-uat",
+    "gate-evaluate",
+    "rewrite-docs",
+];
+export const UNIT_MANIFESTS = {
+    // ─── Milestone-scoped ────────────────────────────────────────────────
+    "research-milestone": {
+        skills: { mode: "all" },
+        knowledge: "full",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        artifacts: {
+            // Phase 3 migration (#4782): matches today's actual
+            // buildResearchMilestonePrompt inlining order.
+            inline: ["milestone-context", "project", "requirements", "decisions", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+    },
+    "plan-milestone": {
+        skills: { mode: "all" },
+        knowledge: "full",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        artifacts: {
+            inline: ["project", "requirements", "decisions", "milestone-research", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_LARGE,
+    },
+    "discuss-milestone": {
+        skills: { mode: "all" },
+        knowledge: "full",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        artifacts: {
+            inline: ["project", "requirements", "decisions", "milestone-context", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+    },
+    "validate-milestone": {
+        skills: { mode: "all" },
+        knowledge: "scoped",
+        memory: "prompt-relevant",
+        codebaseMap: false,
+        preferences: "active-only",
+        artifacts: {
+            inline: ["roadmap", "slice-summary", "slice-uat", "requirements", "decisions", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_LARGE,
+    },
+    "complete-milestone": {
+        skills: { mode: "all" },
+        knowledge: "scoped",
+        memory: "prompt-relevant",
+        codebaseMap: false,
+        preferences: "active-only",
+        artifacts: {
+            // #4780 landed slice-summary as excerpt for this unit; phase 2 of
+            // the architecture will read this manifest as the source of truth
+            // and retire the special-case wiring in auto-prompts.ts.
+            inline: ["roadmap", "milestone-context", "requirements", "decisions", "project", "templates"],
+            excerpt: ["slice-summary"],
+            onDemand: ["slice-summary"],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+    },
+    // ─── Slice-scoped ────────────────────────────────────────────────────
+    "research-slice": {
+        skills: { mode: "all" },
+        knowledge: "full",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        artifacts: {
+            inline: ["roadmap", "milestone-research", "dependency-summaries", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+    },
+    "plan-slice": {
+        skills: { mode: "all" },
+        knowledge: "full",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        artifacts: {
+            inline: ["roadmap", "slice-research", "dependency-summaries", "requirements", "decisions", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_LARGE,
+    },
+    "refine-slice": {
+        skills: { mode: "all" },
+        knowledge: "scoped",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        artifacts: {
+            inline: ["slice-plan", "slice-research", "dependency-summaries", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+    },
+    "replan-slice": {
+        skills: { mode: "all" },
+        knowledge: "scoped",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        artifacts: {
+            inline: ["slice-plan", "slice-research", "dependency-summaries", "prior-task-summaries", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+    },
+    "complete-slice": {
+        skills: { mode: "all" },
+        knowledge: "scoped",
+        memory: "prompt-relevant",
+        codebaseMap: false,
+        preferences: "active-only",
+        artifacts: {
+            // Phase 3 migration (#4782): matches today's actual
+            // buildCompleteSlicePrompt inlining order. Overrides prepend +
+            // knowledge splice stay in the builder imperatively (see RFC
+            // #4924 — computed/prepend blocks are phase-4 composer work).
+            inline: ["roadmap", "slice-context", "slice-plan", "requirements", "prior-task-summaries", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_LARGE,
+    },
+    "reassess-roadmap": {
+        skills: { mode: "all" },
+        knowledge: "scoped",
+        memory: "critical-only",
+        codebaseMap: false,
+        preferences: "none",
+        artifacts: {
+            // Phase 2 pilot (#4782): manifest now matches today's actual
+            // buildReassessRoadmapPrompt behavior for equivalence. Phase 3
+            // will tighten this list once the composer reports real telemetry.
+            inline: ["roadmap", "slice-context", "slice-summary", "project", "requirements", "decisions"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+    },
+    // ─── Task-scoped ─────────────────────────────────────────────────────
+    "execute-task": {
+        skills: { mode: "all" },
+        knowledge: "scoped",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        artifacts: {
+            inline: ["task-plan", "slice-plan", "prior-task-summaries", "templates"],
+            excerpt: [],
+            onDemand: ["slice-research"],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_LARGE,
+    },
+    "reactive-execute": {
+        skills: { mode: "all" },
+        knowledge: "scoped",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        artifacts: {
+            inline: ["slice-plan", "prior-task-summaries", "templates"],
+            excerpt: [],
+            onDemand: ["slice-research"],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_LARGE,
+    },
+    // ─── Ancillary units ─────────────────────────────────────────────────
+    "run-uat": {
+        skills: { mode: "all" },
+        knowledge: "critical-only",
+        memory: "critical-only",
+        codebaseMap: false,
+        preferences: "active-only",
+        artifacts: {
+            // Phase 3 migration (#4782): manifest matches today's actual
+            // buildRunUatPrompt inlining. Prior phase-1 entry listed
+            // `slice-plan` aspirationally — the real builder inlines the UAT
+            // file, the slice SUMMARY (optional), and the project row.
+            inline: ["slice-uat", "slice-summary", "project"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_SMALL,
+    },
+    "gate-evaluate": {
+        skills: { mode: "all" },
+        knowledge: "critical-only",
+        memory: "critical-only",
+        codebaseMap: false,
+        preferences: "active-only",
+        artifacts: {
+            inline: ["slice-plan", "prior-task-summaries"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_SMALL,
+    },
+    "rewrite-docs": {
+        skills: { mode: "all" },
+        knowledge: "scoped",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        artifacts: {
+            inline: ["project", "requirements", "decisions", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+    },
+};
+// ─── Lookup helper ────────────────────────────────────────────────────────
+/**
+ * Return the manifest for a unit type, or null when the type is unknown.
+ *
+ * Callers MUST treat null as "fall through to today's default behavior"
+ * rather than erroring — unknown unit types may be experimental and
+ * should not crash the composer.
+ */
+export function resolveManifest(unitType) {
+    return UNIT_MANIFESTS[unitType] ?? null;
+}

package/dist/resources/extensions/gsd/worktree-manager.js

@@ -20,6 +20,7 @@ import { join, resolve, sep } from "node:path";
 import { GSDError, GSD_PARSE_ERROR, GSD_STALE_STATE, GSD_LOCK_HELD, GSD_GIT_ERROR, GSD_MERGE_CONFLICT } from "./errors.js";
 import { logWarning } from "./workflow-logger.js";
 import { nativeBranchDelete, nativeBranchExists, nativeBranchForceReset, nativeCommit, nativeDetectMainBranch, nativeDiffContent, nativeDiffNameStatus, nativeDiffNumstat, nativeGetCurrentBranch, nativeLogOneline, nativeMergeSquash, nativeWorktreeAdd, nativeWorktreeList, nativeWorktreePrune, nativeWorktreeRemove, } from "./native-git-bridge.js";
+import { emitCanonicalRootRedirect } from "./worktree-telemetry.js";
 // ─── Path Helpers ──────────────────────────────────────────────────────────
 function normalizePathForComparison(path) {
     const normalized = path
@@ -84,6 +85,56 @@ export function isInsideWorktreesDir(basePath, targetPath) {
     // not merely be a prefix match (e.g. ".gsd/worktrees-extra" must not match).
     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, milestoneId) {
+    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 ───────────────────────────────────────────────────────
 /**
  * Create a new git worktree under .gsd/worktrees/<name>/ with branch worktree/<name>.

package/dist/resources/extensions/gsd/worktree-resolver.js

@@ -17,6 +17,9 @@ import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { debugLog } from "./debug-logger.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";
 // ─── Path Helpers ──────────────────────────────────────────────────────────
 /**
  * Worktree marker segment — present in any path produced by worktreePath().
@@ -194,6 +197,20 @@ 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) {
@@ -289,6 +306,9 @@ export class WorktreeResolver {
      */
     mergeAndExit(milestoneId, ctx) {
         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", {
@@ -328,14 +348,68 @@ 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. */
+    /** Worktree-mode merge: read roadmap, merge, teardown, reset paths.
+     *  Returns true when a squash-merge actually ran (false on skip paths). */
     _mergeWorktreeMode(milestoneId, ctx) {
         const originalBase = this.s.originalBasePath;
         if (!originalBase) {
@@ -346,8 +420,9 @@ export class WorktreeResolver {
                 skipped: true,
                 reason: "missing-original-base",
             });
-            return;
+            return false;
         }
+        let merged = false;
         try {
             const { synced } = this.deps.syncWorktreeStateBack(originalBase, this.s.basePath, milestoneId);
             if (synced.length > 0) {
@@ -378,6 +453,7 @@ export class WorktreeResolver {
             if (roadmapPath) {
                 const roadmapContent = this.deps.readFileSync(roadmapPath, "utf-8");
                 const mergeResult = this.deps.mergeMilestoneToMain(originalBase, milestoneId, roadmapContent);
+                merged = true;
                 // #2945 Bug 3: mergeMilestoneToMain performs best-effort worktree
                 // cleanup internally (step 12), but it can silently fail on Windows
                 // or when the worktree directory is locked. Perform a secondary
@@ -470,8 +546,10 @@ export class WorktreeResolver {
             result: "done",
             basePath: this.s.basePath,
         });
+        return merged;
     }
-    /** Branch-mode merge: check current branch, merge if on milestone branch. */
+    /** Branch-mode merge: check current branch, merge if on milestone branch.
+     *  Returns true when a merge actually ran (false on skip paths). */
     _mergeBranchMode(milestoneId, ctx) {
         try {
             const currentBranch = this.deps.getCurrentBranch(this.s.basePath);
@@ -486,7 +564,7 @@ export class WorktreeResolver {
                     currentBranch,
                     milestoneBranch,
                 });
-                return;
+                return false;
             }
             const roadmapPath = this.deps.resolveMilestoneFile(this.s.basePath, milestoneId, "ROADMAP");
             if (!roadmapPath) {
@@ -497,7 +575,7 @@ export class WorktreeResolver {
                     skipped: true,
                     reason: "no-roadmap",
                 });
-                return;
+                return false;
             }
             const roadmapContent = this.deps.readFileSync(roadmapPath, "utf-8");
             const mergeResult = this.deps.mergeMilestoneToMain(this.s.basePath, milestoneId, roadmapContent);
@@ -516,6 +594,7 @@ export class WorktreeResolver {
                 mode: "branch",
                 result: "success",
             });
+            return true;
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);