@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.c18009cd

package/src/resources/extensions/gsd/forensics.ts

@@ -28,11 +28,10 @@ import { deriveState } from "./state.js";
 import { isAutoActive } from "./auto.js";
 import { loadPrompt } from "./prompt-loader.js";
 import { gsdRoot } from "./paths.js";
-import { isDbAvailable, getAllMilestones, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
-import { isClosedStatus } from "./status-guards.js";
+import { isDbAvailable, getHierarchyCompletionCounts } from "./gsd-db.js";
 import { formatDuration } from "../shared/format-utils.js";
 import { getAutoWorktreePath } from "./auto-worktree.js";
-import { loadEffectiveGSDPreferences, loadGlobalGSDPreferences, getGlobalGSDPreferencesPath } from "./preferences.js";
+import { clearGSDPreferencesCache, loadEffectiveGSDPreferences, loadGlobalGSDPreferences, getGlobalGSDPreferencesPath } from "./preferences.js";
 import { showNextAction } from "../shared/tui.js";
 import {
   isInteractiveCommandContext,
@@ -271,6 +270,7 @@ async function writeForensicsDedupPref(ctx: ExtensionCommandContext, enabled: bo
   }
 
   writeFileSync(prefsPath, `---\n${frontmatter}---${body}`, "utf-8");
+  clearGSDPreferencesCache();
 }
 
 // ─── Entry Point ──────────────────────────────────────────────────────────────
@@ -758,37 +758,7 @@ function loadCompletedKeys(basePath: string): string[] {
 function getDbCompletionCounts(): DbCompletionCounts | null {
   if (!isDbAvailable()) return null;
 
-  const milestones = getAllMilestones();
-  let completedMilestones = 0;
-  let totalSlices = 0;
-  let completedSlices = 0;
-  let totalTasks = 0;
-  let completedTasks = 0;
-
-  for (const m of milestones) {
-    if (isClosedStatus(m.status)) completedMilestones++;
-
-    const slices = getMilestoneSlices(m.id);
-    for (const s of slices) {
-      totalSlices++;
-      if (isClosedStatus(s.status)) completedSlices++;
-
-      const tasks = getSliceTasks(m.id, s.id);
-      for (const t of tasks) {
-        totalTasks++;
-        if (isClosedStatus(t.status)) completedTasks++;
-      }
-    }
-  }
-
-  return {
-    milestones: completedMilestones,
-    milestonesTotal: milestones.length,
-    slices: completedSlices,
-    slicesTotal: totalSlices,
-    tasks: completedTasks,
-    tasksTotal: totalTasks,
-  };
+  return getHierarchyCompletionCounts();
 }
 
 // ─── Anomaly Detectors ───────────────────────────────────────────────────────

package/src/resources/extensions/gsd/git-constants.ts

@@ -32,7 +32,7 @@ function buildSafeParentEnv(): NodeJS.ProcessEnv {
 }
 
 /** Env overlay that suppresses interactive git credential prompts and git-svn noise. */
-export const GIT_NO_PROMPT_ENV = {
+export const GIT_NO_PROMPT_ENV: NodeJS.ProcessEnv = {
   ...buildSafeParentEnv(),
   GIT_TERMINAL_PROMPT: "0",
   GIT_ASKPASS: "",

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

@@ -12,12 +12,13 @@
 
 import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import type { Dirent } from "node:fs";
 import { isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
 import { gsdRoot } from "./paths.js";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { logWarning } from "./workflow-logger.js";
-import { createRepositoryRegistryFromPreferences } from "./repository-registry.js";
+import { createRepositoryRegistryFromPreferences, defaultRepositoryTargets } from "./repository-registry.js";
 import { isGsdGitignored } from "./gitignore.js";
 
 
@@ -360,6 +361,7 @@ export interface PreMergeCheckResult {
  */
 export const RUNTIME_EXCLUSION_PATHS: readonly string[] = [
   ".gsd-worktrees/",
+  ".gsd-backups/**",
   ".gsd/activity/",
   ".gsd/audit/",
   ".gsd/forensics/",
@@ -378,6 +380,8 @@ export const RUNTIME_EXCLUSION_PATHS: readonly string[] = [
   ".gsd/DISCUSSION-MANIFEST.json",
 ];
 
+const runtimeFilesCleanedUpRepos = new Set<string>();
+
 // ─── Integration Branch Metadata ───────────────────────────────────────────
 
 /**
@@ -755,7 +759,8 @@ export class GitServiceImpl {
     // and the worktree is torn down. This prevents a mid-execution behavioral
     // discontinuity where the first half of a milestone has .gsd/ artifacts
     // committed but the second half doesn't (#1326).
-    if (!this._runtimeFilesCleanedUp) {
+    const cleanupRepoKey = resolve(this.basePath);
+    if (!runtimeFilesCleanedUpRepos.has(cleanupRepoKey)) {
       let cleaned = false;
       for (const exclusion of RUNTIME_EXCLUSION_PATHS) {
         const removed = nativeRmCached(this.basePath, [exclusion]);
@@ -764,7 +769,7 @@ export class GitServiceImpl {
       if (cleaned) {
         nativeCommit(this.basePath, "chore: untrack .gsd/ runtime files from git index", { allowEmpty: false });
       }
-      this._runtimeFilesCleanedUp = true;
+      runtimeFilesCleanedUpRepos.add(cleanupRepoKey);
     }
 
     // Stage everything using pathspec exclusions so excluded paths are never
@@ -893,9 +898,6 @@ export class GitServiceImpl {
     }
   }
 
-  /** Tracks whether runtime file cleanup has run this session. */
-  private _runtimeFilesCleanedUp = false;
-
   /**
    * Stage files (smart staging) and commit.
    * Returns the commit message string on success, or null if nothing to commit.
@@ -921,16 +923,19 @@ export class GitServiceImpl {
    *
    * Returns the commit message on success, or null if nothing to commit.
    * @param extraExclusions Additional paths to exclude from staging (e.g. [".gsd/"] for pre-switch commits).
+   * @param knownDirty Fresh caller-provided dirty status; when omitted, autoCommit probes the tree.
    */
   autoCommit(
     unitType: string,
     unitId: string,
     extraExclusions: readonly string[] = [],
     taskContext?: TaskCommitContext,
+    knownDirty?: boolean,
   ): string | null {
     // Quick check: is there anything dirty at all?
     // Native path uses libgit2 (single syscall), fallback spawns git.
-    if (!nativeHasChanges(this.basePath)) return null;
+    if (knownDirty === false) return null;
+    if (knownDirty !== true && !nativeHasChanges(this.basePath)) return null;
 
     const scoped = taskContext
       ? this.scopedStageTaskFiles(taskContext, extraExclusions)
@@ -1261,19 +1266,80 @@ export function handleTurnGitActionError(action: TurnGitActionMode, err: unknown
   };
 }
 
+export function isRepositoryDirty(repoRoot: string): boolean {
+  try {
+    return runGit(repoRoot, ["status", "--porcelain"]).length > 0;
+  } catch {
+    // Fallback preserves legacy behavior if explicit status probing fails.
+    return nativeHasChanges(repoRoot);
+  }
+}
+
 function collectRepositoryDirtyStatus(basePath: string): Record<string, boolean> {
   const preferences = loadEffectiveGSDPreferences(basePath)?.preferences;
   const registry = createRepositoryRegistryFromPreferences(basePath, preferences);
   const dirtyByRepository: Record<string, boolean> = {};
+  const registeredRoots = new Set(registry.repositories.map((repo) => resolve(repo.root)));
   for (const repo of registry.repositories) {
+    dirtyByRepository[repo.id] = isRepositoryDirty(repo.root);
+  }
+  for (const repoRoot of findUndeclaredNestedGitRepositories(registry.projectRoot, registeredRoots)) {
+    const dirty = isRepositoryDirty(repoRoot);
+    if (!dirty) continue;
+
+    const relPath = relative(registry.projectRoot, repoRoot).split(sep).join("/") || repoRoot;
+    const label = `${relPath} (undeclared)`;
+    dirtyByRepository[label] = true;
+    logWarning(
+      "engine",
+      `undeclared dirty nested git repo ${relPath}; declare it under workspace.repositories or commit manually`,
+      { file: "git-service.ts" },
+    );
+  }
+  return dirtyByRepository;
+}
+
+const UNDECLARED_NESTED_REPO_SCAN_MAX_DEPTH = 4;
+const UNDECLARED_NESTED_REPO_SKIP_DIRS = new Set([
+  ".git",
+  ".gsd",
+  ".gsd-worktrees",
+  "node_modules",
+  "dist",
+  "dist-test",
+]);
+
+function findUndeclaredNestedGitRepositories(projectRoot: string, registeredRoots: ReadonlySet<string>): string[] {
+  const found: string[] = [];
+
+  function visit(dir: string, depth: number): void {
+    if (depth >= UNDECLARED_NESTED_REPO_SCAN_MAX_DEPTH) return;
+
+    let entries: Dirent[];
     try {
-      dirtyByRepository[repo.id] = runGit(repo.root, ["status", "--porcelain"]).length > 0;
+      entries = readdirSync(dir, { withFileTypes: true });
     } catch {
-      // Fallback preserves legacy behavior if explicit status probing fails.
-      dirtyByRepository[repo.id] = nativeHasChanges(repo.root);
+      return;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (UNDECLARED_NESTED_REPO_SKIP_DIRS.has(entry.name)) continue;
+
+      const child = join(dir, entry.name);
+      const childRoot = resolve(child);
+      const hasGitDir = existsSync(join(child, ".git"));
+      const isRegistered = registeredRoots.has(childRoot);
+      if (hasGitDir && !isRegistered) {
+        found.push(childRoot);
+        continue;
+      }
+      visit(child, depth + 1);
     }
   }
-  return dirtyByRepository;
+
+  visit(projectRoot, 0);
+  return found;
 }
 
 function runPerRepositoryCommitAction(args: {
@@ -1282,6 +1348,7 @@ function runPerRepositoryCommitAction(args: {
   unitId: string;
   taskContext?: TaskCommitContext;
   targetRepositories?: string[];
+  dirtyRepositories?: Record<string, boolean>;
 }): {
   commitMessages: Record<string, string>;
   commitErrors: Record<string, string>;
@@ -1289,7 +1356,7 @@ function runPerRepositoryCommitAction(args: {
 } {
   const preferences = loadEffectiveGSDPreferences(args.basePath)?.preferences;
   const registry = createRepositoryRegistryFromPreferences(args.basePath, preferences);
-  const repoIds = args.targetRepositories?.length ? args.targetRepositories : ["project"];
+  const repoIds = args.targetRepositories?.length ? args.targetRepositories : defaultRepositoryTargets(registry);
   const gitPrefs = preferences?.git ?? {};
   const commitMessages: Record<string, string> = {};
   const commitErrors: Record<string, string> = {};
@@ -1313,6 +1380,7 @@ function runPerRepositoryCommitAction(args: {
           args.unitId,
           [],
           args.taskContext,
+          args.dirtyRepositories?.[repo.id],
         ) ?? "";
       if (message) {
         commitMessages[repo.id] = message;
@@ -1360,7 +1428,7 @@ export function runTurnGitAction(args: {
       };
     }
 
-    const repoCommitResult = runPerRepositoryCommitAction(args);
+    const repoCommitResult = runPerRepositoryCommitAction({ ...args, dirtyRepositories });
     if (Object.keys(repoCommitResult.commitErrors).length > 0) {
       return {
         action: args.action,
@@ -1376,9 +1444,7 @@ export function runTurnGitAction(args: {
       };
     }
 
-    const primaryMessage =
-      repoCommitResult.commitMessages[args.targetRepositories?.[0] ?? "project"]
-      ?? Object.values(repoCommitResult.commitMessages)[0];
+    const primaryMessage = Object.values(repoCommitResult.commitMessages)[0];
     return {
       action: args.action,
       status: "ok",

package/src/resources/extensions/gsd/gitignore.ts

@@ -24,8 +24,9 @@ import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
  * With external state (symlink), these are a no-op in most cases,
  * but retained for backwards compatibility during migration.
  */
-const GSD_RUNTIME_PATTERNS = [
+export const GSD_RUNTIME_PATTERNS = [
   ".gsd-worktrees/",
+  ".gsd-backups/",
   ".gsd/activity/",
   ".gsd/audit/",
   ".gsd/forensics/",
@@ -51,6 +52,8 @@ const BASELINE_PATTERNS = [
   ".gsd",
   // Worktree container sibling — NOT covered by the ".gsd" pattern above.
   ".gsd-worktrees/",
+  // Flat-phase migration snapshots — NOT covered by the ".gsd" pattern above.
+  ".gsd-backups/",
   ".gsd-id",
   ".mcp.json",
   ".bg-shell/",
@@ -221,10 +224,14 @@ export function ensureGitignore(
   );
 
   // Determine which patterns to apply. If .gsd/ has tracked files,
-  // exclude the ".gsd" pattern to prevent deleting tracked state.
+  // exclude the ".gsd" pattern to prevent deleting tracked state, but
+  // substitute the granular GSD_RUNTIME_PATTERNS so transient artifacts
+  // (STATE.md, runtime/, gsd.db, event-log.jsonl, …) still get ignored.
+  // Without this fallback, the pre-completion commit gate sees those
+  // runtime paths as untracked and blocks milestone close-out forever.
   const gsdIsTracked = hasGitTrackedGsdFiles(basePath);
-  const patternsToApply = gsdIsTracked
-    ? BASELINE_PATTERNS.filter((p) => p !== ".gsd")
+  const patternsToApply: readonly string[] = gsdIsTracked
+    ? Array.from(new Set([...BASELINE_PATTERNS.filter((p) => p !== ".gsd"), ...GSD_RUNTIME_PATTERNS]))
     : BASELINE_PATTERNS;
 
   // Find patterns not yet present

package/src/resources/extensions/gsd/gsd-db.ts

@@ -535,6 +535,78 @@ export function updateTaskStatus(milestoneId: string, sliceId: string, taskId: s
   applyStatusTransition({ entity: "task", milestoneId, sliceId, taskId, status, completedAt });
 }
 
+export function repairTaskCompletionFromSummary(t: {
+  milestoneId: string;
+  sliceId: string;
+  taskId: string;
+  title?: string;
+  oneLiner?: string;
+  narrative?: string;
+  verificationResult: string;
+  duration?: string;
+  completedAt: string;
+  blockerDiscovered?: boolean;
+  deviations?: string;
+  knownIssues?: string;
+  keyFiles?: string[];
+  keyDecisions?: string[];
+  fullSummaryMd: string;
+}): void {
+  const db = getDbOrNull();
+  if (!db) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+  transaction(() => {
+    const seq = db.prepare(
+      `SELECT COALESCE(MAX(sequence), 0) + 1 AS next_sequence
+       FROM tasks
+       WHERE milestone_id = :mid AND slice_id = :sid`,
+    ).get({ ":mid": t.milestoneId, ":sid": t.sliceId }) as { next_sequence?: number } | undefined;
+    db.prepare(
+      `INSERT INTO tasks (
+        milestone_id, slice_id, id, title, status, one_liner, narrative,
+        verification_result, duration, completed_at, blocker_discovered,
+        deviations, known_issues, key_files, key_decisions, full_summary_md,
+        sequence
+      ) VALUES (
+        :milestone_id, :slice_id, :id, :title, 'complete', :one_liner, :narrative,
+        :verification_result, :duration, :completed_at, :blocker_discovered,
+        :deviations, :known_issues, :key_files, :key_decisions, :full_summary_md,
+        :sequence
+      )
+      ON CONFLICT(milestone_id, slice_id, id) DO UPDATE SET
+        title = CASE WHEN NULLIF(:title, '') IS NOT NULL THEN :title ELSE tasks.title END,
+        status = 'complete',
+        one_liner = CASE WHEN NULLIF(:one_liner, '') IS NOT NULL THEN :one_liner ELSE tasks.one_liner END,
+        narrative = CASE WHEN NULLIF(:narrative, '') IS NOT NULL THEN :narrative ELSE tasks.narrative END,
+        verification_result = :verification_result,
+        duration = CASE WHEN NULLIF(:duration, '') IS NOT NULL THEN :duration ELSE tasks.duration END,
+        completed_at = :completed_at,
+        blocker_discovered = :blocker_discovered,
+        deviations = CASE WHEN NULLIF(:deviations, '') IS NOT NULL THEN :deviations ELSE tasks.deviations END,
+        known_issues = CASE WHEN NULLIF(:known_issues, '') IS NOT NULL THEN :known_issues ELSE tasks.known_issues END,
+        key_files = :key_files,
+        key_decisions = :key_decisions,
+        full_summary_md = :full_summary_md`,
+    ).run({
+      ":milestone_id": t.milestoneId,
+      ":slice_id": t.sliceId,
+      ":id": t.taskId,
+      ":title": t.title ?? "",
+      ":one_liner": t.oneLiner ?? "",
+      ":narrative": t.narrative ?? "",
+      ":verification_result": t.verificationResult,
+      ":duration": t.duration ?? "",
+      ":completed_at": t.completedAt,
+      ":blocker_discovered": t.blockerDiscovered ? 1 : 0,
+      ":deviations": t.deviations ?? "",
+      ":known_issues": t.knownIssues ?? "",
+      ":key_files": JSON.stringify(t.keyFiles ?? []),
+      ":key_decisions": JSON.stringify(t.keyDecisions ?? []),
+      ":full_summary_md": t.fullSummaryMd,
+      ":sequence": seq?.next_sequence ?? 1,
+    });
+  });
+}
+
 export function setTaskBlockerDiscovered(milestoneId: string, sliceId: string, taskId: string, discovered: boolean): void {
   if (!getDbOrNull()!) return;
   getDbOrNull()!.prepare(

package/src/resources/extensions/gsd/guidance.ts

@@ -192,8 +192,8 @@ export function crashResumeHint(unitType: string, unitId: string): string | unde
 const DOCTOR_FIX_HINTS: Partial<Record<DoctorIssueCode, string>> = {
   db_unavailable:
     "The workflow database could not be opened — state derivation is degraded. Restart the session; if it persists, run `/gsd doctor` from the project root.",
-  stale_crash_lock: "Run `/gsd doctor` to clear the stale lock, then `/gsd auto` to resume.",
-  stale_parallel_session: "Run `/gsd doctor` to clear the stale session registration.",
+  stale_crash_lock: "Run `/gsd doctor fix` to clear the stale lock, then `/gsd auto` to resume.",
+  stale_parallel_session: "Run `/gsd doctor fix` to clear the stale session registration.",
   unresolved_git_conflicts:
     "Resolve the conflict markers, commit, then re-run `/gsd auto`.",
   conflict_markers_in_tracked_files:
@@ -201,14 +201,16 @@ const DOCTOR_FIX_HINTS: Partial<Record<DoctorIssueCode, string>> = {
   worktree_dirty:
     "Commit or merge the worktree's changes (`gsd worktree merge <name>`) before removing it.",
   worktree_branch_merged: "The branch is merged — remove the worktree to reclaim space.",
-  orphaned_auto_worktree: "Run `/gsd doctor` to fix, or merge salvageable work with `gsd worktree merge <name>`.",
-  gitignore_missing_patterns: "Run `/gsd doctor` to append the missing .gitignore patterns.",
+  orphaned_auto_worktree: "Run `/gsd doctor fix` to fix, or merge salvageable work with `gsd worktree merge <name>`.",
+  gitignore_missing_patterns: "Run `/gsd doctor fix` to append the missing .gitignore patterns.",
   invalid_preferences: "Edit .gsd/PREFERENCES.md to fix the invalid field, then re-run the command.",
   provider_key_missing: "Add the provider API key to your environment or provider config, then retry.",
   provider_key_backedoff: "The key is cooling down after repeated failures — wait, or switch the phase model in .gsd/PREFERENCES.md.",
-  state_file_stale: "Run `/gsd doctor` to rebuild the projection from the database.",
-  state_file_missing: "Run `/gsd doctor` to rebuild the projection from the database.",
-  projection_drift: "Run `/gsd doctor` to rebuild markdown projections from the database (DB is the source of truth).",
+  state_file_stale: "Run `/gsd doctor fix` to rebuild the projection from the database.",
+  state_file_missing: "Run `/gsd doctor fix` to rebuild the projection from the database.",
+  projection_drift: "Run `/gsd doctor fix` to rebuild markdown projections from the database (DB is the source of truth).",
+  artifact_user_content_missing:
+    "Doctor cannot recreate user-authored content from the database. Re-run `/gsd discuss` for CONTEXT artifacts or `/gsd auto` for RESEARCH artifacts in that milestone.",
   uat_retry_exhausted: "Review the failing UAT criteria via `/gsd status`, fix the issue, then re-run `/gsd auto`.",
 };
 

package/src/resources/extensions/gsd/guided-flow-queue.ts

@@ -20,6 +20,7 @@ import { invalidateAllCaches } from "./cache.js";
 import {
   gsdRoot, resolveMilestoneFile, resolveSliceFile,
   resolveGsdRootFile, relGsdRootFile, relSliceFile,
+  relMilestoneFile,
 } from "./paths.js";
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
@@ -29,6 +30,10 @@ import { loadQueueOrder, sortByQueueOrder, saveQueueOrder } from "./queue-order.
 import { findMilestoneIds, nextMilestoneId } from "./milestone-ids.js";
 import { isFutureMilestoneStatus } from "./status-guards.js";
 
+const QUEUE_ARTIFACT_EXCERPT_MAX_CHARS = 20_000;
+const QUEUE_EXISTING_MILESTONES_CONTEXT_MAX_CHARS = 120_000;
+const QUEUE_CONTEXT_SECTION_SEPARATOR = "\n\n---\n\n";
+
 // ─── Queue Entry Point ──────────────────────────────────────────────────────
 
 /**
@@ -280,7 +285,9 @@ export async function buildExistingMilestonesContext(
     if (contextFile) {
       const content = await loadFile(contextFile);
       if (content) {
-        parts.push(`\n**Context:**\n${content.trim()}`);
+        parts.push(
+          `\n**Context:**\n${summarizeArtifactForQueue(content, relMilestoneFile(basePath, mid, "CONTEXT"))}`,
+        );
       }
     } else {
       // No full CONTEXT.md — check for CONTEXT-DRAFT.md (draft seed from prior discussion)
@@ -288,7 +295,9 @@ export async function buildExistingMilestonesContext(
       if (draftFile) {
         const draftContent = await loadFile(draftFile);
         if (draftContent) {
-          parts.push(`\n**Draft context available:**\n${draftContent.trim()}`);
+          parts.push(
+            `\n**Draft context available:**\n${summarizeArtifactForQueue(draftContent, relMilestoneFile(basePath, mid, "CONTEXT-DRAFT"))}`,
+          );
         }
       }
     }
@@ -300,7 +309,9 @@ export async function buildExistingMilestonesContext(
       if (roadmapFile) {
         const content = await loadFile(roadmapFile);
         if (content) {
-          parts.push(`\n**Roadmap:**\n${content.trim()}`);
+          parts.push(
+            `\n**Roadmap:**\n${summarizeArtifactForQueue(content, relMilestoneFile(basePath, mid, "ROADMAP"))}`,
+          );
         }
       }
     }
@@ -317,7 +328,81 @@ export async function buildExistingMilestonesContext(
     }
   }
 
-  return sections.join("\n\n---\n\n");
+  return capExistingMilestonesContext(sections);
+}
+
+function summarizeArtifactForQueue(
+  content: string,
+  sourcePath: string,
+  cap = QUEUE_ARTIFACT_EXCERPT_MAX_CHARS,
+): string {
+  const trimmed = content.trim();
+  if (trimmed.length <= cap) {
+    return `Source: \`${sourcePath}\`\n\n${trimmed}`;
+  }
+
+  const excerpt = trimmed.slice(0, cap).trimEnd();
+  const omittedChars = trimmed.length - excerpt.length;
+  return [
+    `Source: \`${sourcePath}\``,
+    "",
+    excerpt,
+    "",
+    `[Truncated ${omittedChars} chars. Read \`${sourcePath}\` for full content.]`,
+  ].join("\n");
+}
+
+function capExistingMilestonesContext(
+  sections: string[],
+  cap = QUEUE_EXISTING_MILESTONES_CONTEXT_MAX_CHARS,
+): string {
+  const fullContext = sections.join(QUEUE_CONTEXT_SECTION_SEPARATOR);
+  if (fullContext.length <= cap) return fullContext;
+
+  const notice = `[Existing milestones context truncated to ${cap} chars. Read source paths in this prompt or the corresponding .gsd artifacts for full details.]`;
+  const noticeSuffix = `${QUEUE_CONTEXT_SECTION_SEPARATOR}${notice}`;
+
+  const selected: string[] = [];
+  for (const section of sections) {
+    const candidate = [...selected, section].join(QUEUE_CONTEXT_SECTION_SEPARATOR) + noticeSuffix;
+    if (candidate.length <= cap) {
+      selected.push(section);
+      continue;
+    }
+    break;
+  }
+
+  if (selected.length === sections.length) {
+    return selected.join(QUEUE_CONTEXT_SECTION_SEPARATOR) + noticeSuffix;
+  }
+
+  const compactTail = sections.slice(selected.length).map(compactSectionForQueueBudget);
+  const hybrid = [...selected, ...compactTail].join(QUEUE_CONTEXT_SECTION_SEPARATOR) + noticeSuffix;
+  if (hybrid.length <= cap) return hybrid;
+
+  const compact = sections.map(compactSectionForQueueBudget);
+  const compactContext = compact.join(QUEUE_CONTEXT_SECTION_SEPARATOR) + noticeSuffix;
+  if (compactContext.length <= cap) return compactContext;
+
+  return `${compactContext.slice(0, Math.max(0, cap - notice.length - 2)).trimEnd()}\n\n${notice}`;
+}
+
+function compactSectionForQueueBudget(section: string): string {
+  const lines = section.split("\n");
+  const compact: string[] = [];
+
+  if (lines[0]) compact.push(lines[0]);
+
+  const statusLine = lines.find(line => line.startsWith("**Status:**"));
+  if (statusLine) compact.push(statusLine);
+
+  const sourceLines = lines.filter(line => line.startsWith("Source: `"));
+  if (sourceLines.length > 0) {
+    compact.push("", "**Sources:**", ...sourceLines);
+    compact.push("", "[Artifact excerpts omitted due to total queue/rethink context budget.]");
+  }
+
+  return compact.join("\n");
 }
 
 // ─── Internal Helpers ───────────────────────────────────────────────────────