gsd-pi 2.16.0 → 2.18.0

package/README.md

@@ -21,6 +21,25 @@ One command. Walk away. Come back to a built project with clean git history.
 
 ---
 
+## Documentation
+
+Full documentation is available in the [`docs/`](./docs/) directory:
+
+- **[Getting Started](./docs/getting-started.md)** — install, first run, basic usage
+- **[Auto Mode](./docs/auto-mode.md)** — autonomous execution deep-dive
+- **[Configuration](./docs/configuration.md)** — all preferences, models, git, and hooks
+- **[Token Optimization](./docs/token-optimization.md)** — profiles, context compression, complexity routing (v2.17)
+- **[Cost Management](./docs/cost-management.md)** — budgets, tracking, projections
+- **[Git Strategy](./docs/git-strategy.md)** — worktree isolation, branching, merge behavior
+- **[Working in Teams](./docs/working-in-teams.md)** — unique IDs, shared artifacts
+- **[Skills](./docs/skills.md)** — bundled skills, discovery, custom authoring
+- **[Commands Reference](./docs/commands.md)** — all commands and keyboard shortcuts
+- **[Architecture](./docs/architecture.md)** — system design and dispatch pipeline
+- **[Troubleshooting](./docs/troubleshooting.md)** — common issues, doctor, recovery
+- **[Migration from v1](./docs/migration.md)** — `.planning` → `.gsd` migration
+
+---
+
 ## What Changed From v1
 
 The original GSD was a collection of markdown prompts installed into `~/.claude/commands/`. It relied entirely on the LLM reading those prompts and doing the right thing. That worked surprisingly well — but it had hard limits:
@@ -334,6 +353,26 @@ unique_milestone_ids: true
 | `skill_rules`          | Situational rules for skill routing                                                                   |
 | `unique_milestone_ids` | Uses unique milestone names to avoid clashes when working in teams of people                          |
 
+### Token Optimization (v2.17)
+
+GSD 2.17 introduced a coordinated token optimization system that reduces usage by 40-60% on cost-sensitive workloads. Set a single preference to coordinate model selection, phase skipping, and context compression:
+
+```yaml
+token_profile: budget      # or balanced (default), quality
+```
+
+| Profile | Savings | What It Does |
+|---------|---------|-------------|
+| `budget` | 40-60% | Cheap models, skip research/reassess, minimal context inlining |
+| `balanced` | 10-20% | Default models, skip slice research, standard context |
+| `quality` | 0% | All phases, all context, full model power |
+
+**Complexity-based routing** automatically classifies tasks as simple/standard/complex and routes to appropriate models. Simple docs tasks get Haiku; complex architectural work gets Opus. The classification is heuristic (sub-millisecond, no LLM calls) and learns from outcomes via a persistent routing history.
+
+**Budget pressure** graduates model downgrading as you approach your budget ceiling — 50%, 75%, and 90% thresholds progressively shift work to cheaper tiers.
+
+See the full [Token Optimization Guide](./docs/token-optimization.md) for details.
+
 ### Bundled Tools
 
 GSD ships with 14 extensions, all loaded automatically:

package/dist/onboarding.js

@@ -633,7 +633,7 @@ async function runRemoteQuestionsStep(p, pc, authStorage) {
         });
         if (p.isCancel(channelId) || !channelId)
             return null;
-        const { saveRemoteQuestionsConfig } = await import('./resources/extensions/remote-questions/remote-command.js');
+        const { saveRemoteQuestionsConfig } = await import('./remote-questions-config.js');
         saveRemoteQuestionsConfig('slack', channelId.trim());
         p.log.success(`Slack channel: ${pc.green(channelId.trim())}`);
         return 'Slack';
@@ -736,7 +736,7 @@ async function runDiscordChannelStep(p, pc, token) {
         channelId = channelChoice;
     }
     // Save remote questions config
-    const { saveRemoteQuestionsConfig } = await import('./resources/extensions/remote-questions/remote-command.js');
+    const { saveRemoteQuestionsConfig } = await import('./remote-questions-config.js');
     saveRemoteQuestionsConfig('discord', channelId);
     const channelName = channels.find(ch => ch.id === channelId)?.name;
     p.log.success(`Discord channel: ${pc.green(channelName ? `#${channelName}` : channelId)}`);

package/dist/remote-questions-config.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Remote Questions Config Helper
+ *
+ * Extracted from remote-questions extension so onboarding.ts can import
+ * it without crossing the compiled/uncompiled boundary. The extension
+ * files in src/resources/ are shipped as raw .ts and loaded via jiti,
+ * but onboarding.ts is compiled by tsc — dynamic imports from compiled
+ * JS to uncompiled .ts fail at runtime (#592).
+ */
+export declare function saveRemoteQuestionsConfig(channel: "slack" | "discord", channelId: string): void;

package/dist/remote-questions-config.js

@@ -0,0 +1,36 @@
+/**
+ * Remote Questions Config Helper
+ *
+ * Extracted from remote-questions extension so onboarding.ts can import
+ * it without crossing the compiled/uncompiled boundary. The extension
+ * files in src/resources/ are shipped as raw .ts and loaded via jiti,
+ * but onboarding.ts is compiled by tsc — dynamic imports from compiled
+ * JS to uncompiled .ts fail at runtime (#592).
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { getGlobalGSDPreferencesPath } from "./resources/extensions/gsd/preferences.js";
+export function saveRemoteQuestionsConfig(channel, channelId) {
+    const prefsPath = getGlobalGSDPreferencesPath();
+    const block = [
+        "remote_questions:",
+        `  channel: ${channel}`,
+        `  channel_id: "${channelId}"`,
+        "  timeout_minutes: 5",
+        "  poll_interval_seconds: 5",
+    ].join("\n");
+    const content = existsSync(prefsPath) ? readFileSync(prefsPath, "utf-8") : "";
+    const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+    let next = content;
+    if (fmMatch) {
+        let frontmatter = fmMatch[1];
+        const regex = /remote_questions:[\s\S]*?(?=\n[a-zA-Z_]|\n---|$)/;
+        frontmatter = regex.test(frontmatter) ? frontmatter.replace(regex, block) : `${frontmatter.trimEnd()}\n${block}`;
+        next = `---\n${frontmatter}\n---${content.slice(fmMatch[0].length)}`;
+    }
+    else {
+        next = `---\n${block}\n---\n\n${content}`;
+    }
+    mkdirSync(dirname(prefsPath), { recursive: true });
+    writeFileSync(prefsPath, next, "utf-8");
+}

package/dist/resources/extensions/gsd/activity-log.ts

@@ -8,7 +8,7 @@
  * Diagnostic extraction is handled by session-forensics.ts.
  */
 
-import { writeFileSync, mkdirSync, readdirSync, unlinkSync, statSync, openSync, closeSync, constants } from "node:fs";
+import { writeFileSync, writeSync, mkdirSync, readdirSync, unlinkSync, statSync, openSync, closeSync, constants } from "node:fs";
 import { createHash } from "node:crypto";
 import { join } from "node:path";
 
@@ -23,6 +23,15 @@ interface ActivityLogState {
 
 const activityLogState = new Map<string, ActivityLogState>();
 
+/**
+ * Clear accumulated activity log state (#611).
+ * Call when auto-mode stops to prevent unbounded memory growth
+ * from lastSnapshotKeyByUnit maps accumulating across units.
+ */
+export function clearActivityLogState(): void {
+  activityLogState.clear();
+}
+
 function scanNextSequence(activityDir: string): number {
   let maxSeq = 0;
   try {
@@ -46,9 +55,21 @@ function getActivityState(activityDir: string): ActivityLogState {
   return state;
 }
 
-function snapshotKey(unitType: string, unitId: string, content: string): string {
-  const digest = createHash("sha1").update(content).digest("hex");
-  return `${unitType}\0${unitId}\0${digest}`;
+/**
+ * Build a lightweight dedup key from session entries without serializing
+ * the entire content to a string (#611). Uses entry count + hash of
+ * the last few entries as a fingerprint instead of hashing megabytes.
+ */
+function snapshotKey(unitType: string, unitId: string, entries: unknown[]): string {
+  const hash = createHash("sha1");
+  hash.update(`${unitType}\0${unitId}\0${entries.length}\0`);
+  // Hash only the last 3 entries as a fingerprint — if the session grew,
+  // the count change alone detects it; if content changed, the tail hash catches it.
+  const tail = entries.slice(-3);
+  for (const entry of tail) {
+    hash.update(JSON.stringify(entry));
+  }
+  return hash.digest("hex");
 }
 
 function nextActivityFilePath(
@@ -91,14 +112,23 @@ export function saveActivityLog(
     mkdirSync(activityDir, { recursive: true });
 
     const safeUnitId = unitId.replace(/\//g, "-");
-    const content = `${entries.map(entry => JSON.stringify(entry)).join("\n")}\n`;
     const state = getActivityState(activityDir);
     const unitKey = `${unitType}\0${safeUnitId}`;
-    const key = snapshotKey(unitType, safeUnitId, content);
+    // Use lightweight fingerprint instead of serializing all entries (#611)
+    const key = snapshotKey(unitType, safeUnitId, entries);
     if (state.lastSnapshotKeyByUnit.get(unitKey) === key) return;
 
     const filePath = nextActivityFilePath(activityDir, state, unitType, safeUnitId);
-    writeFileSync(filePath, content, "utf-8");
+    // Stream entries to disk line-by-line instead of building one massive string (#611).
+    // For large sessions, the single-string approach allocated hundreds of MB.
+    const fd = openSync(filePath, "w");
+    try {
+      for (const entry of entries) {
+        writeSync(fd, JSON.stringify(entry) + "\n");
+      }
+    } finally {
+      closeSync(fd);
+    }
     state.nextSeq += 1;
     state.lastSnapshotKeyByUnit.set(unitKey, key);
   } catch (e) {

package/dist/resources/extensions/gsd/auto-dashboard.ts

@@ -35,6 +35,10 @@ export interface AutoDashboardData {
   /** Running cost and token totals from metrics ledger */
   totalCost: number;
   totalTokens: number;
+  /** Projected remaining cost based on unit-type averages (undefined if insufficient data) */
+  projectedRemainingCost?: number;
+  /** Whether token profile has been auto-downgraded due to budget prediction */
+  profileDowngraded?: boolean;
 }
 
 // ─── Unit Description Helpers ─────────────────────────────────────────────────

package/dist/resources/extensions/gsd/auto-dispatch.ts

@@ -122,7 +122,9 @@ const DISPATCH_RULES: DispatchRule[] = [
   },
   {
     name: "reassess-roadmap (post-completion)",
-    match: async ({ state, mid, midTitle, basePath }) => {
+    match: async ({ state, mid, midTitle, basePath, prefs }) => {
+      // Phase skip: skip reassess when preference or profile says so
+      if (prefs?.phases?.skip_reassess) return null;
       const needsReassess = await checkNeedsReassessment(basePath, mid, state);
       if (!needsReassess) return null;
       return {
@@ -160,8 +162,10 @@ const DISPATCH_RULES: DispatchRule[] = [
   },
   {
     name: "pre-planning (no research) → research-milestone",
-    match: async ({ state, mid, midTitle, basePath }) => {
+    match: async ({ state, mid, midTitle, basePath, prefs }) => {
       if (state.phase !== "pre-planning") return null;
+      // Phase skip: skip research when preference or profile says so
+      if (prefs?.phases?.skip_research) return null;
       const researchFile = resolveMilestoneFile(basePath, mid, "RESEARCH");
       if (researchFile) return null; // has research, fall through
       return {
@@ -186,8 +190,10 @@ const DISPATCH_RULES: DispatchRule[] = [
   },
   {
     name: "planning (no research, not S01) → research-slice",
-    match: async ({ state, mid, midTitle, basePath }) => {
+    match: async ({ state, mid, midTitle, basePath, prefs }) => {
       if (state.phase !== "planning") return null;
+      // Phase skip: skip research when preference or profile says so
+      if (prefs?.phases?.skip_research || prefs?.phases?.skip_slice_research) return null;
       const sid = state.activeSlice!.id;
       const sTitle = state.activeSlice!.title;
       const researchFile = resolveSliceFile(basePath, mid, sid, "RESEARCH");

package/dist/resources/extensions/gsd/auto-prompts.ts

@@ -15,8 +15,8 @@ import {
   relMilestoneFile, relSliceFile, relSlicePath, relMilestonePath,
   resolveGsdRootFile, relGsdRootFile,
 } from "./paths.js";
-import { resolveSkillDiscoveryMode } from "./preferences.js";
-import type { GSDState } from "./types.js";
+import { resolveSkillDiscoveryMode, resolveInlineLevel } from "./preferences.js";
+import type { GSDState, InlineLevel } from "./types.js";
 import type { GSDPreferences } from "./preferences.js";
 import { join } from "node:path";
 import { existsSync } from "node:fs";
@@ -89,7 +89,7 @@ export async function inlineDependencySummaries(
 export async function inlineGsdRootFile(
   base: string, filename: string, label: string,
 ): Promise<string | null> {
-  const key = filename.replace(/\.md$/i, "").toUpperCase() as "PROJECT" | "DECISIONS" | "QUEUE" | "STATE" | "REQUIREMENTS";
+  const key = filename.replace(/\.md$/i, "").toUpperCase() as "PROJECT" | "DECISIONS" | "QUEUE" | "STATE" | "REQUIREMENTS" | "KNOWLEDGE";
   const absPath = resolveGsdRootFile(base, key);
   if (!existsSync(absPath)) return null;
   return inlineFileOptional(absPath, relGsdRootFile(key), label);
@@ -377,6 +377,8 @@ export async function buildResearchMilestonePrompt(mid: string, midTitle: string
   if (requirementsInline) inlined.push(requirementsInline);
   const decisionsInline = await inlineGsdRootFile(base, "decisions.md", "Decisions");
   if (decisionsInline) inlined.push(decisionsInline);
+  const knowledgeInlineRM = await inlineGsdRootFile(base, "knowledge.md", "Project Knowledge");
+  if (knowledgeInlineRM) inlined.push(knowledgeInlineRM);
   inlined.push(inlineTemplate("research", "Research"));
 
   const inlinedContext = `## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`;
@@ -393,7 +395,8 @@ export async function buildResearchMilestonePrompt(mid: string, midTitle: string
   });
 }
 
-export async function buildPlanMilestonePrompt(mid: string, midTitle: string, base: string): Promise<string> {
+export async function buildPlanMilestonePrompt(mid: string, midTitle: string, base: string, level?: InlineLevel): Promise<string> {
+  const inlineLevel = level ?? resolveInlineLevel();
   const contextPath = resolveMilestoneFile(base, mid, "CONTEXT");
   const contextRel = relMilestoneFile(base, mid, "CONTEXT");
   const researchPath = resolveMilestoneFile(base, mid, "RESEARCH");
@@ -406,17 +409,25 @@ export async function buildPlanMilestonePrompt(mid: string, midTitle: string, ba
   const { inlinePriorMilestoneSummary } = await import("./files.js");
   const priorSummaryInline = await inlinePriorMilestoneSummary(mid, base);
   if (priorSummaryInline) inlined.push(priorSummaryInline);
-  const projectInline = await inlineGsdRootFile(base, "project.md", "Project");
+  const projectInline = inlineLevel !== "minimal" ? await inlineGsdRootFile(base, "project.md", "Project") : null;
   if (projectInline) inlined.push(projectInline);
-  const requirementsInline = await inlineGsdRootFile(base, "requirements.md", "Requirements");
+  const requirementsInline = inlineLevel !== "minimal" ? await inlineGsdRootFile(base, "requirements.md", "Requirements") : null;
   if (requirementsInline) inlined.push(requirementsInline);
-  const decisionsInline = await inlineGsdRootFile(base, "decisions.md", "Decisions");
+  const decisionsInline = inlineLevel !== "minimal" ? await inlineGsdRootFile(base, "decisions.md", "Decisions") : null;
   if (decisionsInline) inlined.push(decisionsInline);
+  const knowledgeInlinePM = await inlineGsdRootFile(base, "knowledge.md", "Project Knowledge");
+  if (knowledgeInlinePM) inlined.push(knowledgeInlinePM);
   inlined.push(inlineTemplate("roadmap", "Roadmap"));
-  inlined.push(inlineTemplate("decisions", "Decisions"));
-  inlined.push(inlineTemplate("plan", "Slice Plan"));
-  inlined.push(inlineTemplate("task-plan", "Task Plan"));
-  inlined.push(inlineTemplate("secrets-manifest", "Secrets Manifest"));
+  if (inlineLevel === "full") {
+    inlined.push(inlineTemplate("decisions", "Decisions"));
+    inlined.push(inlineTemplate("plan", "Slice Plan"));
+    inlined.push(inlineTemplate("task-plan", "Task Plan"));
+    inlined.push(inlineTemplate("secrets-manifest", "Secrets Manifest"));
+  } else if (inlineLevel === "standard") {
+    inlined.push(inlineTemplate("decisions", "Decisions"));
+    inlined.push(inlineTemplate("plan", "Slice Plan"));
+    inlined.push(inlineTemplate("task-plan", "Task Plan"));
+  }
 
   const inlinedContext = `## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`;
 
@@ -454,6 +465,8 @@ export async function buildResearchSlicePrompt(
   if (decisionsInline) inlined.push(decisionsInline);
   const requirementsInline = await inlineGsdRootFile(base, "requirements.md", "Requirements");
   if (requirementsInline) inlined.push(requirementsInline);
+  const knowledgeInlineRS = await inlineGsdRootFile(base, "knowledge.md", "Project Knowledge");
+  if (knowledgeInlineRS) inlined.push(knowledgeInlineRS);
   inlined.push(inlineTemplate("research", "Research"));
 
   const depContent = await inlineDependencySummaries(mid, sid, base);
@@ -479,8 +492,9 @@ export async function buildResearchSlicePrompt(
 }
 
 export async function buildPlanSlicePrompt(
-  mid: string, _midTitle: string, sid: string, sTitle: string, base: string,
+  mid: string, _midTitle: string, sid: string, sTitle: string, base: string, level?: InlineLevel,
 ): Promise<string> {
+  const inlineLevel = level ?? resolveInlineLevel();
   const roadmapPath = resolveMilestoneFile(base, mid, "ROADMAP");
   const roadmapRel = relMilestoneFile(base, mid, "ROADMAP");
   const researchPath = resolveSliceFile(base, mid, sid, "RESEARCH");
@@ -490,12 +504,18 @@ export async function buildPlanSlicePrompt(
   inlined.push(await inlineFile(roadmapPath, roadmapRel, "Milestone Roadmap"));
   const researchInline = await inlineFileOptional(researchPath, researchRel, "Slice Research");
   if (researchInline) inlined.push(researchInline);
-  const decisionsInline = await inlineGsdRootFile(base, "decisions.md", "Decisions");
-  if (decisionsInline) inlined.push(decisionsInline);
-  const requirementsInline = await inlineGsdRootFile(base, "requirements.md", "Requirements");
-  if (requirementsInline) inlined.push(requirementsInline);
+  if (inlineLevel !== "minimal") {
+    const decisionsInline = await inlineGsdRootFile(base, "decisions.md", "Decisions");
+    if (decisionsInline) inlined.push(decisionsInline);
+    const requirementsInline = await inlineGsdRootFile(base, "requirements.md", "Requirements");
+    if (requirementsInline) inlined.push(requirementsInline);
+  }
+  const knowledgeInlinePS = await inlineGsdRootFile(base, "knowledge.md", "Project Knowledge");
+  if (knowledgeInlinePS) inlined.push(knowledgeInlinePS);
   inlined.push(inlineTemplate("plan", "Slice Plan"));
-  inlined.push(inlineTemplate("task-plan", "Task Plan"));
+  if (inlineLevel === "full") {
+    inlined.push(inlineTemplate("task-plan", "Task Plan"));
+  }
 
   const depContent = await inlineDependencySummaries(mid, sid, base);
   const planActiveOverrides = await loadActiveOverrides(base);
@@ -519,8 +539,9 @@ export async function buildPlanSlicePrompt(
 
 export async function buildExecuteTaskPrompt(
   mid: string, sid: string, sTitle: string,
-  tid: string, tTitle: string, base: string,
+  tid: string, tTitle: string, base: string, level?: InlineLevel,
 ): Promise<string> {
+  const inlineLevel = level ?? resolveInlineLevel();
 
   const priorSummaries = await getPriorTaskSummaryPaths(mid, sid, tid, base);
   const priorLines = priorSummaries.length > 0
@@ -560,11 +581,22 @@ export async function buildExecuteTaskPrompt(
     legacyContinuePath ? `${relSlicePath(base, mid, sid)}/continue.md` : null,
   );
 
-  const carryForwardSection = await buildCarryForwardSection(priorSummaries, base);
-  const inlinedTemplates = [
-    inlineTemplate("task-summary", "Task Summary"),
-    inlineTemplate("decisions", "Decisions"),
-  ].join("\n\n---\n\n");
+  // For minimal inline level, only carry forward the most recent prior summary
+  const effectivePriorSummaries = inlineLevel === "minimal" && priorSummaries.length > 1
+    ? priorSummaries.slice(-1)
+    : priorSummaries;
+  const carryForwardSection = await buildCarryForwardSection(effectivePriorSummaries, base);
+
+  // Inline project knowledge if available
+  const knowledgeInlineET = await inlineGsdRootFile(base, "knowledge.md", "Project Knowledge");
+
+  const inlinedTemplates = inlineLevel === "minimal"
+    ? inlineTemplate("task-summary", "Task Summary")
+    : [
+        inlineTemplate("task-summary", "Task Summary"),
+        inlineTemplate("decisions", "Decisions"),
+        ...(knowledgeInlineET ? [knowledgeInlineET] : []),
+      ].join("\n\n---\n\n");
 
   const taskSummaryPath = `${relSlicePath(base, mid, sid)}/tasks/${tid}-SUMMARY.md`;
 
@@ -589,8 +621,9 @@ export async function buildExecuteTaskPrompt(
 }
 
 export async function buildCompleteSlicePrompt(
-  mid: string, _midTitle: string, sid: string, sTitle: string, base: string,
+  mid: string, _midTitle: string, sid: string, sTitle: string, base: string, level?: InlineLevel,
 ): Promise<string> {
+  const inlineLevel = level ?? resolveInlineLevel();
 
   const roadmapPath = resolveMilestoneFile(base, mid, "ROADMAP");
   const roadmapRel = relMilestoneFile(base, mid, "ROADMAP");
@@ -600,8 +633,12 @@ export async function buildCompleteSlicePrompt(
   const inlined: string[] = [];
   inlined.push(await inlineFile(roadmapPath, roadmapRel, "Milestone Roadmap"));
   inlined.push(await inlineFile(slicePlanPath, slicePlanRel, "Slice Plan"));
-  const requirementsInline = await inlineGsdRootFile(base, "requirements.md", "Requirements");
-  if (requirementsInline) inlined.push(requirementsInline);
+  if (inlineLevel !== "minimal") {
+    const requirementsInline = await inlineGsdRootFile(base, "requirements.md", "Requirements");
+    if (requirementsInline) inlined.push(requirementsInline);
+  }
+  const knowledgeInlineCS = await inlineGsdRootFile(base, "knowledge.md", "Project Knowledge");
+  if (knowledgeInlineCS) inlined.push(knowledgeInlineCS);
 
   // Inline all task summaries for this slice
   const tDir = resolveTasksDir(base, mid, sid);
@@ -618,7 +655,9 @@ export async function buildCompleteSlicePrompt(
     }
   }
   inlined.push(inlineTemplate("slice-summary", "Slice Summary"));
-  inlined.push(inlineTemplate("uat", "UAT"));
+  if (inlineLevel !== "minimal") {
+    inlined.push(inlineTemplate("uat", "UAT"));
+  }
   const completeActiveOverrides = await loadActiveOverrides(base);
   const completeOverridesInline = formatOverridesSection(completeActiveOverrides);
   if (completeOverridesInline) inlined.unshift(completeOverridesInline);
@@ -641,8 +680,9 @@ export async function buildCompleteSlicePrompt(
 }
 
 export async function buildCompleteMilestonePrompt(
-  mid: string, midTitle: string, base: string,
+  mid: string, midTitle: string, base: string, level?: InlineLevel,
 ): Promise<string> {
+  const inlineLevel = level ?? resolveInlineLevel();
   const roadmapPath = resolveMilestoneFile(base, mid, "ROADMAP");
   const roadmapRel = relMilestoneFile(base, mid, "ROADMAP");
 
@@ -663,13 +703,17 @@ export async function buildCompleteMilestonePrompt(
     }
   }
 
-  // Inline root GSD files
-  const requirementsInline = await inlineGsdRootFile(base, "requirements.md", "Requirements");
-  if (requirementsInline) inlined.push(requirementsInline);
-  const decisionsInline = await inlineGsdRootFile(base, "decisions.md", "Decisions");
-  if (decisionsInline) inlined.push(decisionsInline);
-  const projectInline = await inlineGsdRootFile(base, "project.md", "Project");
-  if (projectInline) inlined.push(projectInline);
+  // Inline root GSD files (skip for minimal — completion can read these if needed)
+  if (inlineLevel !== "minimal") {
+    const requirementsInline = await inlineGsdRootFile(base, "requirements.md", "Requirements");
+    if (requirementsInline) inlined.push(requirementsInline);
+    const decisionsInline = await inlineGsdRootFile(base, "decisions.md", "Decisions");
+    if (decisionsInline) inlined.push(decisionsInline);
+    const projectInline = await inlineGsdRootFile(base, "project.md", "Project");
+    if (projectInline) inlined.push(projectInline);
+  }
+  const knowledgeInlineCM = await inlineGsdRootFile(base, "knowledge.md", "Project Knowledge");
+  if (knowledgeInlineCM) inlined.push(knowledgeInlineCM);
   // Inline milestone context file (milestone-level, not GSD root)
   const contextPath = resolveMilestoneFile(base, mid, "CONTEXT");
   const contextRel = relMilestoneFile(base, mid, "CONTEXT");
@@ -779,8 +823,9 @@ export async function buildRunUatPrompt(
 }
 
 export async function buildReassessRoadmapPrompt(
-  mid: string, midTitle: string, completedSliceId: string, base: string,
+  mid: string, midTitle: string, completedSliceId: string, base: string, level?: InlineLevel,
 ): Promise<string> {
+  const inlineLevel = level ?? resolveInlineLevel();
   const roadmapPath = resolveMilestoneFile(base, mid, "ROADMAP");
   const roadmapRel = relMilestoneFile(base, mid, "ROADMAP");
   const summaryPath = resolveSliceFile(base, mid, completedSliceId, "SUMMARY");
@@ -789,12 +834,16 @@ export async function buildReassessRoadmapPrompt(
   const inlined: string[] = [];
   inlined.push(await inlineFile(roadmapPath, roadmapRel, "Current Roadmap"));
   inlined.push(await inlineFile(summaryPath, summaryRel, `${completedSliceId} Summary`));
-  const projectInline = await inlineGsdRootFile(base, "project.md", "Project");
-  if (projectInline) inlined.push(projectInline);
-  const requirementsInline = await inlineGsdRootFile(base, "requirements.md", "Requirements");
-  if (requirementsInline) inlined.push(requirementsInline);
-  const decisionsInline = await inlineGsdRootFile(base, "decisions.md", "Decisions");
-  if (decisionsInline) inlined.push(decisionsInline);
+  if (inlineLevel !== "minimal") {
+    const projectInline = await inlineGsdRootFile(base, "project.md", "Project");
+    if (projectInline) inlined.push(projectInline);
+    const requirementsInline = await inlineGsdRootFile(base, "requirements.md", "Requirements");
+    if (requirementsInline) inlined.push(requirementsInline);
+    const decisionsInline = await inlineGsdRootFile(base, "decisions.md", "Decisions");
+    if (decisionsInline) inlined.push(decisionsInline);
+  }
+  const knowledgeInlineRA = await inlineGsdRootFile(base, "knowledge.md", "Project Knowledge");
+  if (knowledgeInlineRA) inlined.push(knowledgeInlineRA);
 
   const inlinedContext = `## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`;
 

package/dist/resources/extensions/gsd/auto-recovery.ts

@@ -11,6 +11,7 @@ import type { ExtensionContext } from "@gsd/pi-coding-agent";
 import {
   clearUnitRuntimeRecord,
 } from "./unit-runtime.js";
+import { clearParseCache } from "./files.js";
 import {
   nativeConflictFiles,
   nativeCommit,
@@ -107,9 +108,13 @@ export function verifyExpectedArtifact(unitType: string, unitId: string, base: s
   // is managed by the hook engine, not the artifact verification system.
   if (unitType.startsWith("hook/")) return true;
 
-  // Clear stale directory listing cache so artifact checks see fresh disk state (#431).
-  // Moved after hook check to avoid unnecessary cache clears for hook units.
+  // Clear stale directory listing cache AND parse cache so artifact checks see
+  // fresh disk state (#431). The parse cache must also be cleared because
+  // cacheKey() uses length + first/last 100 chars — when a checkbox changes
+  // from [ ] to [x], the key collides with the pre-edit version, returning
+  // stale parsed results (e.g., slice.done = false when it's actually true).
   clearPathCache();
+  clearParseCache();
 
   if (unitType === "rewrite-docs") {
     const overridesPath = resolveGsdRootFile(base, "OVERRIDES");

package/dist/resources/extensions/gsd/auto-worktree.ts

@@ -14,8 +14,10 @@ import {
   removeWorktree,
   worktreePath,
 } from "./worktree-manager.js";
+import { detectWorktreeName } from "./worktree.js";
 import {
   MergeConflictError,
+  readIntegrationBranch,
 } from "./git-service.js";
 import { parseRoadmap } from "./files.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
@@ -90,7 +92,12 @@ export function autoWorktreeBranch(milestoneId: string): string {
  */
 export function createAutoWorktree(basePath: string, milestoneId: string): string {
   const branch = autoWorktreeBranch(milestoneId);
-  const info = createWorktree(basePath, milestoneId, { branch });
+
+  // Use the integration branch recorded in META.json as the start point.
+  // This ensures the worktree branch is created from the branch the user
+  // was on when they started the milestone (e.g. f-setup-gsd-2), not main.
+  const integrationBranch = readIntegrationBranch(basePath, milestoneId) ?? undefined;
+  const info = createWorktree(basePath, milestoneId, { branch, startPoint: integrationBranch });
 
   // Copy .gsd/ planning artifacts from the source repo into the new worktree.
   // Worktrees are fresh git checkouts — untracked files don't carry over.
@@ -224,6 +231,27 @@ export function getAutoWorktreeOriginalBase(): string | null {
   return originalBase;
 }
 
+export function getActiveAutoWorktreeContext(): {
+  originalBase: string;
+  worktreeName: string;
+  branch: string;
+} | null {
+  if (!originalBase) return null;
+  const cwd = process.cwd();
+  const resolvedBase = existsSync(originalBase) ? realpathSync(originalBase) : originalBase;
+  const wtDir = join(resolvedBase, ".gsd", "worktrees");
+  if (!cwd.startsWith(wtDir)) return null;
+  const worktreeName = detectWorktreeName(cwd);
+  if (!worktreeName) return null;
+  const branch = nativeGetCurrentBranch(cwd);
+  if (!branch.startsWith("milestone/")) return null;
+  return {
+    originalBase,
+    worktreeName,
+    branch,
+  };
+}
+
 // ─── Merge Milestone -> Main ───────────────────────────────────────────────
 
 /**
@@ -279,11 +307,12 @@ export function mergeMilestoneToMain(
   const previousCwd = process.cwd();
   process.chdir(originalBasePath_);
 
-  // 4. Resolve main branch from preferences
+  // 4. Resolve integration branch — prefer milestone metadata, fall back to preferences / "main"
   const prefs = loadEffectiveGSDPreferences()?.preferences?.git ?? {};
-  const mainBranch = prefs.main_branch || "main";
+  const integrationBranch = readIntegrationBranch(originalBasePath_, milestoneId);
+  const mainBranch = integrationBranch ?? prefs.main_branch ?? "main";
 
-  // 5. Checkout main
+  // 5. Checkout integration branch
   nativeCheckoutBranch(originalBasePath_, mainBranch);
 
   // 6. Build rich commit message