@opengsd/gsd-pi 1.0.2-dev.e9a1b49 → 1.0.2-dev.fb7ddf1

package/src/resources/extensions/gsd/unit-context-manifest.ts

@@ -13,6 +13,8 @@
 //
 // Phased rollout tracking:
 //   - Phase 1 (this PR): schema + manifests + coverage test.
+//   - Phase 1b (skill token savings): skills policy wired via skill-scope.ts
+//     and setVisibleSkills(); allowlists derived from skill-manifest.ts.
 //   - 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
@@ -277,11 +279,20 @@ export interface UnitContextManifest {
 
 // ─── 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.
+// Phase 1 policy: skills policy is derived from skill-manifest.ts allowlists
+// via `skillPolicyForUnit()`; units without an allowlist keep mode "all".
+// Explicit mode "none" remains for lightweight config units.
+
+import { resolveSkillManifest } from "./skill-manifest.js";
+
+/** Derive skills policy from skill-manifest allowlists; default to full catalog. */
+function skillPolicyForUnit(unitType: string): SkillsPolicy {
+  const allowlist = resolveSkillManifest(unitType);
+  if (allowlist) {
+    return { mode: "allowlist", skills: allowlist };
+  }
+  return { mode: "all" };
+}
 
 const COMMON_BUDGET_LARGE = 1_500_000;  // ~400K tokens
 const COMMON_BUDGET_MEDIUM = 750_000;   // ~200K tokens
@@ -360,7 +371,7 @@ export type UnitType = typeof KNOWN_UNIT_TYPES[number];
 export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
   // ─── Milestone-scoped ────────────────────────────────────────────────
   "research-milestone": {
-    skills: { mode: "all" },
+    skills: skillPolicyForUnit("research-milestone"),
     knowledge: "full",
     memory: "prompt-relevant",
     codebaseMap: true,
@@ -377,7 +388,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
   },
   "plan-milestone": {
-    skills: { mode: "all" },
+    skills: skillPolicyForUnit("plan-milestone"),
     knowledge: "full",
     memory: "prompt-relevant",
     codebaseMap: true,
@@ -392,7 +403,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     maxSystemPromptChars: COMMON_BUDGET_LARGE,
   },
   "discuss-milestone": {
-    skills: { mode: "all" },
+    skills: skillPolicyForUnit("discuss-milestone"),
     knowledge: "full",
     memory: "prompt-relevant",
     codebaseMap: true,
@@ -407,7 +418,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
   },
   "validate-milestone": {
-    skills: { mode: "all" },
+    skills: skillPolicyForUnit("validate-milestone"),
     knowledge: "scoped",
     memory: "prompt-relevant",
     codebaseMap: false,
@@ -424,7 +435,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     maxSystemPromptChars: COMMON_BUDGET_LARGE,
   },
   "complete-milestone": {
-    skills: { mode: "all" },
+    skills: skillPolicyForUnit("complete-milestone"),
     knowledge: "scoped",
     memory: "prompt-relevant",
     codebaseMap: false,
@@ -446,7 +457,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
 
   // ─── Slice-scoped ────────────────────────────────────────────────────
   "research-slice": {
-    skills: { mode: "all" },
+    skills: skillPolicyForUnit("research-slice"),
     knowledge: "full",
     memory: "prompt-relevant",
     codebaseMap: true,
@@ -463,7 +474,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
   },
   "plan-slice": {
-    skills: { mode: "all" },
+    skills: skillPolicyForUnit("plan-slice"),
     knowledge: "full",
     memory: "prompt-relevant",
     codebaseMap: true,
@@ -481,7 +492,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     maxSystemPromptChars: COMMON_BUDGET_LARGE,
   },
   "refine-slice": {
-    skills: { mode: "all" },
+    skills: skillPolicyForUnit("refine-slice"),
     knowledge: "scoped",
     memory: "prompt-relevant",
     codebaseMap: true,
@@ -499,7 +510,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
   },
   "replan-slice": {
-    skills: { mode: "all" },
+    skills: skillPolicyForUnit("replan-slice"),
     knowledge: "scoped",
     memory: "prompt-relevant",
     codebaseMap: true,
@@ -514,7 +525,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
   },
   "complete-slice": {
-    skills: { mode: "all" },
+    skills: skillPolicyForUnit("complete-slice"),
     knowledge: "scoped",
     memory: "prompt-relevant",
     codebaseMap: false,
@@ -535,7 +546,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     maxSystemPromptChars: COMMON_BUDGET_LARGE,
   },
   "reassess-roadmap": {
-    skills: { mode: "all" },
+    skills: skillPolicyForUnit("reassess-roadmap"),
     knowledge: "scoped",
     memory: "critical-only",
     codebaseMap: false,
@@ -552,7 +563,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
 
   // ─── Task-scoped ─────────────────────────────────────────────────────
   "execute-task": {
-    skills: { mode: "all" },
+    skills: skillPolicyForUnit("execute-task"),
     knowledge: "scoped",
     memory: "prompt-relevant",
     codebaseMap: true,
@@ -567,7 +578,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     maxSystemPromptChars: COMMON_BUDGET_LARGE,
   },
   "reactive-execute": {
-    skills: { mode: "all" },
+    skills: skillPolicyForUnit("reactive-execute"),
     knowledge: "scoped",
     memory: "prompt-relevant",
     codebaseMap: true,
@@ -584,7 +595,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
 
   // ─── Ancillary units ─────────────────────────────────────────────────
   "run-uat": {
-    skills: { mode: "all" },
+    skills: skillPolicyForUnit("run-uat"),
     knowledge: "critical-only",
     memory: "critical-only",
     codebaseMap: false,
@@ -599,7 +610,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     maxSystemPromptChars: COMMON_BUDGET_SMALL,
   },
   "gate-evaluate": {
-    skills: { mode: "all" },
+    skills: skillPolicyForUnit("gate-evaluate"),
     knowledge: "critical-only",
     memory: "critical-only",
     codebaseMap: false,
@@ -616,7 +627,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     maxSystemPromptChars: COMMON_BUDGET_SMALL,
   },
   "rewrite-docs": {
-    skills: { mode: "all" },
+    skills: skillPolicyForUnit("rewrite-docs"),
     knowledge: "scoped",
     memory: "prompt-relevant",
     codebaseMap: true,
@@ -631,7 +642,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
   },
   "triage-captures": {
-    skills: { mode: "all" },
+    skills: skillPolicyForUnit("triage-captures"),
     knowledge: "scoped",
     memory: "prompt-relevant",
     codebaseMap: false,
@@ -646,7 +657,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
   },
   "quick-task": {
-    skills: { mode: "all" },
+    skills: skillPolicyForUnit("quick-task"),
     knowledge: "full",
     memory: "prompt-relevant",
     codebaseMap: true,
@@ -684,7 +695,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
   // discussion runs before any milestone exists, so milestone artifacts are
   // not loaded. Keeps templates available for PROJECT.md scaffolding.
   "discuss-project": {
-    skills: { mode: "all" },
+    skills: skillPolicyForUnit("discuss-project"),
     knowledge: "scoped",
     memory: "prompt-relevant",
     codebaseMap: true,
@@ -701,7 +712,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
   // discuss-requirements: REQUIREMENTS.md interview. PROJECT.md is the
   // primary context input; templates carry the requirements format.
   "discuss-requirements": {
-    skills: { mode: "all" },
+    skills: skillPolicyForUnit("discuss-requirements"),
     knowledge: "scoped",
     memory: "prompt-relevant",
     codebaseMap: true,
@@ -737,7 +748,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
   // planning-dispatch policy to dispatch them. PROJECT.md + REQUIREMENTS.md
   // give the orchestrator the framing context.
   "research-project": {
-    skills: { mode: "all" },
+    skills: skillPolicyForUnit("research-project"),
     knowledge: "scoped",
     memory: "prompt-relevant",
     codebaseMap: true,

package/src/resources/extensions/gsd/user-input-boundary.ts

@@ -39,7 +39,7 @@ function extractTextFromMessage(msg: unknown): string {
   return parts.join("\n");
 }
 
-function lastAssistantText(messages: unknown[] | undefined): string {
+export function lastAssistantText(messages: unknown[] | null | undefined): string {
   if (!Array.isArray(messages)) return "";
   for (let i = messages.length - 1; i >= 0; i--) {
     const msg = messages[i];

package/src/resources/extensions/gsd/vision-ask.ts

@@ -0,0 +1,28 @@
+/**
+ * Natural-language openers for milestone discussion.
+ *
+ * Keep these short and conversational. They are often the user's first prompt
+ * when GSD starts shaping a project or milestone, so they should feel like a
+ * collaborator starting a working session rather than a form field.
+ */
+import { randomInt } from "node:crypto";
+
+export const VISION_ASK_VARIANTS = [
+  "What are we building?",
+  "What do you want to make next?",
+  "What should this become?",
+  "What are you picturing?",
+  "Where should we take this?",
+  "What should this milestone unlock?",
+  "Tell me what you want to build.",
+  "What should GSD help you shape?",
+] as const;
+
+export type VisionAskVariant = typeof VISION_ASK_VARIANTS[number];
+
+export function chooseVisionAskVariant(
+  pickIndex: (exclusiveMax: number) => number = randomInt,
+): VisionAskVariant {
+  const index = pickIndex(VISION_ASK_VARIANTS.length);
+  return VISION_ASK_VARIANTS[index] ?? VISION_ASK_VARIANTS[0];
+}

package/src/resources/extensions/gsd/visualizer-overlay.ts

@@ -1,5 +1,5 @@
 import type { Theme } from "@gsd/pi-coding-agent";
-import { truncateToWidth, visibleWidth, matchesKey, Key } from "@gsd/pi-tui";
+import { visibleWidth, matchesKey, Key } from "@gsd/pi-tui";
 import { loadVisualizerData, type VisualizerData } from "./visualizer-data.js";
 import {
   renderProgressView,
@@ -19,6 +19,7 @@ import { join } from "node:path";
 import { writeExportFile } from "./export.js";
 import { gsdRoot } from "./paths.js";
 import { stripAnsi } from "../shared/mod.js";
+import { renderDialogFrame, renderKeyHints } from "./tui/render-kit.js";
 
 export const TAB_COUNT = 10;
 const TAB_LABELS = [
@@ -500,8 +501,7 @@ export class GSDVisualizerOverlay {
 
     // Apply scroll
     const viewportHeight = Math.max(5, process.stdout.rows ? process.stdout.rows - 8 : 24);
-    const chromeHeight = 2;
-    const visibleContentRows = Math.max(1, viewportHeight - chromeHeight);
+    const visibleContentRows = Math.max(1, viewportHeight - 4);
     this.lastVisibleRows = visibleContentRows;
     const totalLines = content.length;
     const maxScroll = Math.max(0, content.length - visibleContentRows);
@@ -509,49 +509,21 @@ export class GSDVisualizerOverlay {
     const offset = this.scrollOffsets[this.activeTab];
     const visibleContent = content.slice(offset, offset + visibleContentRows);
 
-    const lines = this.wrapInBox(visibleContent, width, offset, visibleContentRows, totalLines);
-
-    // Footer hint
-    const hint = th.fg("dim", "Tab/Shift+Tab/1-9,0 switch \u00b7 / filter \u00b7 PgUp/PgDn scroll \u00b7 ? help \u00b7 esc close");
-    const hintVis = visibleWidth(hint);
-    const hintPad = Math.max(0, Math.floor((width - hintVis) / 2));
-    lines.push(" ".repeat(hintPad) + hint);
+    const footer = renderKeyHints(
+      th,
+      ["Tab/Shift+Tab/1-9,0 switch", "/ filter", "PgUp/PgDn scroll", "? help", "esc close"],
+      Math.max(1, width - 4),
+    );
+    const lines = renderDialogFrame(th, "GSD Visualizer", visibleContent, width, {
+      footer,
+      scroll: { offset, visibleRows: visibleContentRows, totalRows: totalLines },
+    });
 
     this.cachedWidth = width;
     this.cachedLines = lines;
     return lines;
   }
 
-  private wrapInBox(inner: string[], width: number, offset?: number, visibleRows?: number, totalLines?: number): string[] {
-    const th = this.theme;
-    const border = (s: string) => th.fg("borderAccent", s);
-    const innerWidth = width - 4;
-    const lines: string[] = [];
-    lines.push(border("\u256d" + "\u2500".repeat(width - 2) + "\u256e"));
-
-    // Compute scroll indicator positions
-    const scrollable = totalLines !== undefined && visibleRows !== undefined && totalLines > visibleRows;
-    let thumbStart = -1;
-    let thumbLen = 0;
-    const innerRows = inner.length;
-    if (scrollable && innerRows > 0 && totalLines! > 0) {
-      thumbStart = Math.round(((offset ?? 0) / totalLines!) * innerRows);
-      thumbLen = Math.max(1, Math.round((visibleRows! / totalLines!) * innerRows));
-    }
-
-    for (let i = 0; i < inner.length; i++) {
-      const line = inner[i];
-      const truncated = truncateToWidth(line, innerWidth);
-      const padWidth = Math.max(0, innerWidth - visibleWidth(truncated));
-      const rightBorder = scrollable && i >= thumbStart && i < thumbStart + thumbLen
-        ? border("\u2503")
-        : border("\u2502");
-      lines.push(border("\u2502") + " " + truncated + " ".repeat(padWidth) + " " + rightBorder);
-    }
-    lines.push(border("\u2570" + "\u2500".repeat(width - 2) + "\u256f"));
-    return lines;
-  }
-
   invalidate(): void {
     this.cachedWidth = undefined;
     this.cachedLines = undefined;

package/src/resources/extensions/gsd/worktree-lifecycle.ts

@@ -216,6 +216,10 @@ export type EnterResult =
       cause?: unknown;
     };
 
+export interface StrandedMilestoneAdoptionOptions {
+  mode: "worktree" | "branch";
+}
+
 export type ExitResult =
   | { ok: true; merged: boolean; codeFilesChanged: boolean }
   | { ok: false; reason: "merge-conflict" | "teardown-failed"; cause?: unknown };
@@ -237,6 +241,8 @@ export interface MergeContext {
    */
   worktreeBasePath: string;
   milestoneId: string;
+  /** Temporary override used while recovering stranded work. */
+  isolationModeOverride?: "worktree" | "branch" | "none";
   /**
    * When true, `mergeMilestoneStandalone` returns `{ merged: false,
    * mode: "skipped" }` immediately (mirrors the single-loop guard). Default
@@ -533,6 +539,7 @@ export function _enterMilestoneCore(
   deps: WorktreeLifecycleDeps,
   milestoneId: string,
   ctx: NotifyCtx,
+  opts: { modeOverride?: "worktree" | "branch" } = {},
 ): EnterResult {
   if (!isValidMilestoneId(milestoneId)) {
     debugLog("WorktreeLifecycle", {
@@ -653,7 +660,7 @@ export function _enterMilestoneCore(
   // Handles the case where originalBasePath is falsy and basePath is itself
   // a worktree path — prevents double-nested worktree paths (#3729).
   const basePath = resolveWorktreeProjectRoot(s.basePath, s.originalBasePath);
-  const mode = getIsolationMode(basePath);
+  const mode = opts.modeOverride ?? getIsolationMode(basePath);
 
   if (s.isolationDegraded) {
     if (mode === "worktree") {
@@ -1298,7 +1305,9 @@ export function mergeMilestoneStandalone(
     };
   }
 
-  const mode = getIsolationMode(originalBasePath || worktreeBasePath);
+  const mode =
+    mctx.isolationModeOverride ??
+    getIsolationMode(originalBasePath || worktreeBasePath);
   debugLog("WorktreeLifecycle", {
     action: "mergeAndExit",
     milestoneId,
@@ -1637,6 +1646,7 @@ export class WorktreeLifecycle {
         originalBasePath: this.s.originalBasePath,
         worktreeBasePath: this.s.basePath,
         milestoneId,
+        isolationModeOverride: this.s.strandedRecoveryIsolationMode ?? undefined,
         isolationDegraded: this.s.isolationDegraded,
         notify: ctx.notify,
       });
@@ -1740,6 +1750,7 @@ export class WorktreeLifecycle {
       // Rebuild GitService after merge (branch HEAD changed)
       rebuildGitService(this.s, this.deps);
     }
+    this.s.strandedRecoveryIsolationMode = null;
     return result;
   }
 
@@ -1876,6 +1887,30 @@ export class WorktreeLifecycle {
     this.s.basePath = resolvePausedResumeBasePath(base, persistedWorktreePath);
   }
 
+  /**
+   * Adopt in-progress stranded work during bootstrap.
+   *
+   * Unlike completed-orphan recovery, this does not merge, delete, or commit.
+   * It only moves the live session onto the branch/worktree proven by the
+   * audit evidence, while preserving that mode for the eventual merge.
+   */
+  adoptStrandedMilestone(
+    milestoneId: string,
+    base: string,
+    ctx: NotifyCtx,
+    opts: StrandedMilestoneAdoptionOptions,
+  ): EnterResult {
+    this.adoptSessionRoot(base);
+    this.s.strandedRecoveryIsolationMode = opts.mode;
+    const result = _enterMilestoneCore(this.s, this.deps, milestoneId, ctx, {
+      modeOverride: opts.mode,
+    });
+    if (!result.ok) {
+      this.s.strandedRecoveryIsolationMode = null;
+    }
+    return result;
+  }
+
   /**
    * Adopt an orphan worktree for a bootstrap-time merge (ADR-016 phase 2 / B4,
    * issue #5622).

package/src/resources/extensions/gsd/worktree-post-create-hook.ts

@@ -0,0 +1,127 @@
+// Project/App: gsd-pi
+// File Purpose: Lightweight worktree post-create hook runner.
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+
+import { parse as parseYaml } from "yaml";
+
+import { gsdHome } from "./gsd-home.js";
+import { gsdRoot } from "./paths.js";
+
+function readPreferencesObject(path: string): Record<string, unknown> | null {
+  if (!existsSync(path)) return null;
+
+  const content = readFileSync(path, "utf-8");
+  try {
+    const startMarker = content.startsWith("---\r\n") ? "---\r\n" : "---\n";
+    if (content.startsWith(startMarker)) {
+      const searchStart = startMarker.length;
+      const endIdx = content.indexOf("\n---", searchStart);
+      if (endIdx === -1) return null;
+
+      const parsed = parseYaml(content.slice(searchStart, endIdx).replace(/\r/g, ""));
+      return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+        ? parsed as Record<string, unknown>
+        : null;
+    }
+
+    const gitLines: string[] = [];
+    let inGitSection = false;
+    for (const rawLine of content.split("\n")) {
+      const line = rawLine.replace(/\r$/, "");
+      const heading = line.match(/^##\s+(.+)$/);
+      if (heading) {
+        inGitSection = heading[1].trim().toLowerCase().replace(/\s+/g, "_") === "git";
+        continue;
+      }
+      if (inGitSection && line.trim() && !line.trimStart().startsWith("#")) {
+        gitLines.push(line.replace(/^\s*-\s*/, ""));
+      }
+    }
+    if (gitLines.length === 0) return null;
+
+    const parsed = parseYaml(gitLines.join("\n"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? { git: parsed as Record<string, unknown> }
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function extractHookPath(preferences: Record<string, unknown> | null): string | null {
+  const git = preferences?.git;
+  if (!git || typeof git !== "object" || Array.isArray(git)) return null;
+  const hookPath = (git as Record<string, unknown>).worktree_post_create;
+  return typeof hookPath === "string" && hookPath.trim() ? hookPath : null;
+}
+
+function resolveConfiguredHookPath(sourceDir: string): string | null {
+  const paths = [
+    join(homedir(), ".pi", "agent", "gsd-preferences.md"),
+    join(gsdHome(), "preferences.md"),
+    join(gsdHome(), "PREFERENCES.md"),
+    join(gsdRoot(sourceDir), "preferences.md"),
+    join(gsdRoot(sourceDir), "PREFERENCES.md"),
+  ];
+
+  let hookPath: string | null = null;
+  for (const path of paths) {
+    hookPath = extractHookPath(readPreferencesObject(path)) ?? hookPath;
+  }
+  return hookPath;
+}
+
+/**
+ * Run the user-configured post-create hook script after worktree creation.
+ * The script receives SOURCE_DIR and WORKTREE_DIR as environment variables.
+ * Failure is non-fatal -- returns the error message or null on success.
+ *
+ * Reads git.worktree_post_create from effective global/project preferences
+ * unless hookPath is provided directly.
+ */
+export function runWorktreePostCreateHook(
+  sourceDir: string,
+  worktreeDir: string,
+  hookPath?: string,
+): string | null {
+  if (hookPath === undefined) {
+    hookPath = resolveConfiguredHookPath(sourceDir) ?? undefined;
+  }
+  if (!hookPath) return null;
+
+  let resolved = isAbsolute(hookPath) ? hookPath : join(sourceDir, hookPath);
+  if (!existsSync(resolved)) {
+    return `Worktree post-create hook not found: ${resolved}`;
+  }
+  if (process.platform === "win32") {
+    try {
+      resolved = realpathSync.native(resolved);
+    } catch {
+      // Keep the original path; the exec error below will include the failure.
+    }
+  }
+
+  try {
+    const needsShell = process.platform === "win32" && /\.(bat|cmd)$/i.test(resolved);
+    execFileSync(resolved, [], {
+      cwd: worktreeDir,
+      env: {
+        ...process.env,
+        SOURCE_DIR: sourceDir,
+        WORKTREE_DIR: worktreeDir,
+      },
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+      timeout: 30_000,
+      shell: needsShell,
+    });
+    return null;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return `Worktree post-create hook failed: ${msg}`;
+  }
+}

package/src/resources/extensions/gsd/worktree-state-projection.ts

@@ -172,6 +172,35 @@ const ROOT_DIAGNOSTIC_FILES = [
   "metrics.json",
 ] as const;
 
+/**
+ * Root-level .gsd/ projections copied from project root into worktrees for
+ * compatibility reads. Project root remains authoritative; copy-back still
+ * excludes these markdown projections.
+ */
+const ROOT_FORWARD_PROJECTION_FILES = [
+  "DECISIONS.md",
+  "REQUIREMENTS.md",
+  "PROJECT.md",
+  "KNOWLEDGE.md",
+  "OVERRIDES.md",
+  "QUEUE.md",
+  "completed-units.json",
+  "metrics.json",
+  "mcp.json",
+] as const;
+
+function syncRootProjectionFilesToWorktree(prGsd: string, wtGsd: string): void {
+  mkdirSync(wtGsd, { recursive: true });
+
+  for (const file of ROOT_FORWARD_PROJECTION_FILES) {
+    const src = join(prGsd, file);
+    const dst = join(wtGsd, file);
+    if (!existsSync(src) || existsSync(dst)) continue;
+
+    safeCopy(src, dst, { force: false });
+  }
+}
+
 // ─── Implementation cores ────────────────────────────────────────────────
 //
 // The `_*Impl` exports take raw paths so the deprecated path-string
@@ -204,6 +233,10 @@ export function _projectRootToWorktreeImpl(
   // Compare realpaths and skip when they resolve to the same physical path (#2184).
   if (isSamePath(prGsd, wtGsd)) return;
 
+  // Root PROJECT/REQUIREMENTS/DECISIONS projections must be readable from a
+  // worktree-bound unit; the project root remains authoritative.
+  syncRootProjectionFilesToWorktree(prGsd, wtGsd);
+
   // Copy milestone directory from project root to worktree — additive only.
   // force:false prevents cpSync from overwriting existing worktree files.
   // Without this, worktree-local files (e.g. VALIDATION.md written