gsd-pi 2.76.0 → 2.77.0-dev.1594b263e

package/src/resources/extensions/gsd/prompts/parallel-research-slices.md

@@ -15,8 +15,11 @@ Dispatch ALL slices simultaneously using the `subagent` tool in **parallel mode*
 1. Call `subagent` with `tasks: [...]` containing one entry per slice below
 2. Wait for ALL subagents to complete
 3. Verify each slice's RESEARCH file was written (check the `.gsd/{{mid}}/` directory)
-4. If any subagent failed to write its RESEARCH file, re-run it individually
-5. Report which slices completed research and which (if any) failed
+4. If a subagent failed to write its RESEARCH file, retry it **once** individually
+5. If it fails a second time, write a partial RESEARCH file for that slice with a `## BLOCKER` section explaining the failure — do NOT retry again
+6. Report which slices completed research and which (if any) needed a blocker note
+
+**Important**: Each failed slice gets exactly one retry. After that, write the blocker and move on. Never retry the same slice more than once.
 
 ## Subagent Prompts
 

package/src/resources/extensions/gsd/prompts/plan-slice.md

@@ -20,9 +20,22 @@ Pay particular attention to **Forward Intelligence** sections — they contain h
 
 You have full tool access. Before decomposing, explore the relevant code to ground your plan in reality.
 
-### Verify Roadmap Assumptions
+### Verify Roadmap Assumptions (JIT Reassessment — ADR-003 §4)
 
-Check prior slice summaries (inlined above as dependency summaries, if present). If prior slices discovered constraints, changed approaches, or flagged fragility, adjust your plan accordingly. The roadmap description may be stale — verify it against the current codebase state.
+Before planning this slice, verify that the roadmap's assumptions still hold given prior slice summaries. Check inlined dependency summaries (below) for discovered constraints, changed approaches, or flagged fragility.
+
+**If the remaining roadmap needs adjustment, modify it before proceeding:**
+
+- If a downstream slice's title/demo/dependencies are now wrong, call `gsd_reassess_roadmap` with the corrected `sliceChanges.modified` entry.
+- If new work surfaced that deserves its own slice, add it via `sliceChanges.added`.
+- If a downstream slice is now redundant or out of scope, remove it via `sliceChanges.removed`.
+- **Bias strongly toward "roadmap is fine."** Most slice completions produce no structural change. Only adjust when there is concrete evidence a downstream slice is wrong — not speculative concern. Over-reassessment is costlier than a later mid-slice replan.
+
+Completed slices are immutable: never modify or remove a slice whose status is complete.
+
+Then proceed with planning this slice against the (possibly updated) roadmap.
+
+The roadmap description may be stale — verify it against the current codebase state.
 
 ### Explore Slice Scope
 
@@ -44,6 +57,7 @@ Narrate your decomposition reasoning — why you're grouping work this way, what
 
 Then:
 0. If `REQUIREMENTS.md` was preloaded above, identify which Active requirements the roadmap says this slice owns or supports. These are the requirements this plan must deliver — every owned requirement needs at least one task that directly advances it, and verification must prove the requirement is met.
+0a. Call `memory_query` with keywords from the slice title and the source files listed below. Prior architectural decisions, conventions, and gotchas in this area should inform task decomposition — not be re-derived during execution.
 1. Read the templates:
    - `~/.gsd/agent/extensions/gsd/templates/plan.md`
    - `~/.gsd/agent/extensions/gsd/templates/task-plan.md`

package/src/resources/extensions/gsd/prompts/research-slice.md

@@ -42,6 +42,7 @@ An honest "this is straightforward, here's the pattern to follow" is more valuab
 
 Research what this slice needs. Narrate key findings and surprises as you go — what exists, what's missing, what constrains the approach.
 0. If `REQUIREMENTS.md` was preloaded above, identify which Active requirements this slice owns or supports. Research should target these requirements — surfacing risks, unknowns, and implementation constraints that could affect whether the slice actually delivers them.
+0a. Call `memory_query` with keywords from the slice title and scope. Prior slices may have captured architecture notes, conventions, or gotchas in subsystems you're about to explore — pulling them now prevents re-discovering known constraints.
 1. {{skillActivation}} Reference specific rules from loaded skills in your findings where they inform the implementation approach.
 2. **Skill Discovery ({{skillDiscoveryMode}}):**{{skillDiscoveryInstructions}}
 3. Explore relevant code for this slice's scope. For targeted exploration, use `rg`, `find`, and reads. For broad or unfamiliar subsystems, use `scout` to map the relevant area first.

package/src/resources/extensions/gsd/prompts/system.md

@@ -213,6 +213,7 @@ Fix the root cause, not symptoms. When applying a temporary mitigation, label it
 - State uncertainty plainly: "Not sure this handles X - testing it." No performed confidence, no hedging paragraphs.
 - All user-visible narration must be grammatical English. Do not emit compressed planner notes like "Need inspect X" or "Maybe read Y first". If it would look acceptable in a commit comment or standup note, it's acceptable here.
 - When debugging, stay curious. Problems are puzzles. Say what's interesting about the failure before reaching for fixes.
+- After completing a task, give a brief completion summary and present 2-4 contextual next-step options as a numbered list (the last option is always "Other"). This reduces cognitive load by letting the user pick rather than formulate what's next. Omit the numbered list when the response must follow a strict output format (JSON, patches, commit messages, structured data).
 
 Good narration: "Three existing handlers follow a middleware pattern - using that instead of a custom wrapper."
 Good narration: "Tests pass. Running slice-level verification."

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

@@ -14,8 +14,9 @@
  * Manual: /gsd export --html
  */
 
-import { writeFileSync, readFileSync, mkdirSync, existsSync } from 'node:fs';
+import { readFileSync, mkdirSync, existsSync } from 'node:fs';
 import { join, basename } from 'node:path';
+import { atomicWriteSync } from './atomic-write.js';
 import { gsdRoot } from './paths.js';
 import { formatCost, formatTokenCount } from './metrics.js';
 import { formatDateShort, formatDuration } from '../shared/format-utils.js';
@@ -83,7 +84,7 @@ export function loadReportsIndex(basePath: string): ReportsIndex | null {
 function saveReportsIndex(basePath: string, index: ReportsIndex): void {
   const dir = reportsDir(basePath);
   mkdirSync(dir, { recursive: true });
-  writeFileSync(reportsIndexPath(basePath), JSON.stringify(index, null, 2) + '\n', 'utf-8');
+  atomicWriteSync(reportsIndexPath(basePath), JSON.stringify(index, null, 2) + '\n', 'utf-8');
 }
 
 // ─── Write a report snapshot ──────────────────────────────────────────────────
@@ -121,7 +122,7 @@ export function writeReportSnapshot(args: WriteReportSnapshotArgs): string {
   const filename = `${prefix}-${timestamp}.html`;
   const filePath = join(dir, filename);
 
-  writeFileSync(filePath, args.html, 'utf-8');
+  atomicWriteSync(filePath, args.html, 'utf-8');
 
   // Load or init registry
   const existing = loadReportsIndex(args.basePath);
@@ -170,7 +171,7 @@ export function writeReportSnapshot(args: WriteReportSnapshotArgs): string {
 
 export function regenerateHtmlIndex(basePath: string, index: ReportsIndex): void {
   const html = buildIndexHtml(index);
-  writeFileSync(reportsHtmlIndexPath(basePath), html, 'utf-8');
+  atomicWriteSync(reportsHtmlIndexPath(basePath), html, 'utf-8');
 }
 
 function buildIndexHtml(index: ReportsIndex): string {

package/src/resources/extensions/gsd/safety/evidence-collector.ts

@@ -3,10 +3,26 @@
  * Tracks every bash command, file write, and file edit during a unit execution.
  * Evidence is compared against LLM completion claims in evidence-cross-ref.ts.
  *
+ * Evidence is persisted to .gsd/safety/evidence-<mid>-<sid>-<tid>.json so it
+ * survives session restarts (pause/resume, crash recovery). On unit start,
+ * call resetEvidence() then loadEvidenceFromDisk(). On every new tool call,
+ * saveEvidenceToDisk() is called automatically by recordToolCall/recordToolResult.
+ *
  * Follows the same module-level Map pattern as auto-tool-tracking.ts.
  * Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
  */
 
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  unlinkSync,
+} from "node:fs";
+import { join, dirname } from "node:path";
+import { randomBytes } from "node:crypto";
+
 // ─── Types ──────────────────────────────────────────────────────────────────
 
 export interface BashEvidence {
@@ -62,6 +78,109 @@ export function getFilePaths(): string[] {
     .map(e => e.path);
 }
 
+// ─── Persistence (Bug #4385 — evidence must survive session restarts) ────────
+
+/**
+ * Build the path for the evidence JSON file for a given unit.
+ * Lives under .gsd/safety/ which is gitignored and session-scoped.
+ */
+function evidencePath(basePath: string, milestoneId: string, sliceId: string, taskId: string): string {
+  return join(basePath, ".gsd", "safety", `evidence-${milestoneId}-${sliceId}-${taskId}.json`);
+}
+
+/**
+ * Validate that a parsed value is an array of EvidenceEntry objects.
+ * Rejects corrupt / schema-mismatch data rather than letting it poison state.
+ */
+function isEvidenceArray(data: unknown): data is EvidenceEntry[] {
+  if (!Array.isArray(data)) return false;
+  return data.every((e) => {
+    if (e === null || typeof e !== "object") return false;
+    const rec = e as Record<string, unknown>;
+    if (typeof rec.toolCallId !== "string") return false;
+    if (typeof rec.timestamp !== "number") return false;
+    if (rec.kind === "bash") {
+      return (
+        typeof rec.command === "string" &&
+        typeof rec.exitCode === "number" &&
+        typeof rec.outputSnippet === "string"
+      );
+    }
+    if (rec.kind === "write" || rec.kind === "edit") {
+      return typeof rec.path === "string";
+    }
+    return false;
+  });
+}
+
+/**
+ * Persist the current in-memory evidence to disk so it survives a session
+ * restart. Called from saveEvidenceToDisk after recordToolCall/recordToolResult.
+ * Non-fatal — persistence failures must never break unit execution.
+ */
+export function saveEvidenceToDisk(
+  basePath: string,
+  milestoneId: string,
+  sliceId: string,
+  taskId: string,
+): void {
+  try {
+    const path = evidencePath(basePath, milestoneId, sliceId, taskId);
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp.${randomBytes(4).toString("hex")}`;
+    writeFileSync(tmp, JSON.stringify(unitEvidence, null, 2) + "\n", "utf-8");
+    renameSync(tmp, path);
+  } catch {
+    // Non-fatal — don't let persistence failures break unit execution
+  }
+}
+
+/**
+ * Load persisted evidence from disk into the in-memory array.
+ * Call after resetEvidence() on session resume to restore context for a
+ * partially-executed unit. If the file does not exist (fresh unit), this
+ * is a no-op — getEvidence() will return [] which is correct.
+ */
+export function loadEvidenceFromDisk(
+  basePath: string,
+  milestoneId: string,
+  sliceId: string,
+  taskId: string,
+): void {
+  try {
+    const path = evidencePath(basePath, milestoneId, sliceId, taskId);
+    if (!existsSync(path)) return;
+    const raw = readFileSync(path, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (isEvidenceArray(parsed)) {
+      unitEvidence = parsed;
+    }
+  } catch {
+    // Non-fatal — corrupt / missing file is treated as empty evidence
+  }
+}
+
+/**
+ * Delete the persisted evidence file for a unit after it has been fully
+ * processed. Prevents stale evidence from affecting future retries of
+ * the same unit ID.
+ */
+export function clearEvidenceFromDisk(
+  basePath: string,
+  milestoneId: string,
+  sliceId: string,
+  taskId: string,
+): void {
+  try {
+    const path = evidencePath(basePath, milestoneId, sliceId, taskId);
+    if (existsSync(path)) {
+      unlinkSync(path);
+    }
+  } catch {
+    // Non-fatal
+  }
+}
+
 // ─── Recording (called from register-hooks.ts) ─────────────────────────────
 
 /**

package/src/resources/extensions/gsd/safety/file-change-validator.ts

@@ -4,15 +4,23 @@
  *
  * Uses tasks.expected_output (DB column, populated from per-task ## Expected Output)
  * and tasks.files (from slice PLAN.md - Files: subline) as the expected set.
- * Compares against git diff HEAD~1 --name-only after auto-commit.
+ * Compares against `git diff-tree --root --no-commit-id -r --name-only HEAD` after auto-commit.
+ * Using diff-tree --root handles initial commits, shallow clones, and merge commits correctly
+ * (Bug #4385 — git diff HEAD~1 failed on initial commits).
  *
  * Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
  */
 
+import { createRequire } from "node:module";
 import { execFileSync } from "node:child_process";
 import { normalizePlannedFileReference } from "../files.js";
 import { logWarning } from "../workflow-logger.js";
 
+const _require = createRequire(import.meta.url);
+type PicomatchMatcher = (input: string) => boolean;
+type PicomatchFn = (pattern: string, opts?: { dot?: boolean }) => PicomatchMatcher;
+const picomatch = _require("picomatch") as PicomatchFn;
+
 // ─── Types ──────────────────────────────────────────────────────────────────
 
 export interface FileViolation {
@@ -43,6 +51,7 @@ export function validateFileChanges(
   basePath: string,
   expectedOutput: string[],
   plannedFiles: string[],
+  fileChangeAllowlist: string[] = [],
 ): FileChangeAudit | null {
   const allExpected = new Set([...expectedOutput, ...plannedFiles]);
 
@@ -63,8 +72,12 @@ export function validateFileChanges(
     ),
   );
 
-  // Compute symmetric difference
-  const unexpectedFiles = projectFiles.filter(f => !normalizedExpected.has(f));
+  // Build allowlist matchers once (dot: true so patterns like `**/.hidden` work).
+  const allowlistMatchers = fileChangeAllowlist.map(p => picomatch(p, { dot: true }));
+  const isAllowlisted = (f: string) => allowlistMatchers.some(m => m(f));
+
+  // Compute symmetric difference, excluding allowlisted files
+  const unexpectedFiles = projectFiles.filter(f => !normalizedExpected.has(f) && !isAllowlisted(f));
   const missingFiles = [...normalizedExpected].filter(f => !projectFiles.includes(f));
 
   const violations: FileViolation[] = [];
@@ -100,7 +113,7 @@ function getChangedFilesFromLastCommit(basePath: string): string[] | null {
   try {
     const result = execFileSync(
       "git",
-      ["diff", "--name-only", "HEAD~1", "HEAD"],
+      ["diff-tree", "--root", "--no-commit-id", "-r", "--name-only", "HEAD"],
       { cwd: basePath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" },
     ).trim();
     return result ? result.split("\n").filter(Boolean) : [];

package/src/resources/extensions/gsd/safety/git-checkpoint.ts

@@ -72,6 +72,21 @@ export function rollbackToCheckpoint(
       return false;
     }
 
+    // Preserve any staged or untracked user work before the hard reset.
+    // The user may have a partial fix staged that they wanted to inspect;
+    // reset --hard wipes both staged and unstaged changes (reflog only
+    // covers committed state). Push a labeled stash first so recovery
+    // is possible. (Issue #4980 HIGH-4)
+    try {
+      execFileSync(
+        "git",
+        ["stash", "push", "--include-untracked", "-m", `gsd: pre-rollback-stash ${unitId} ${new Date().toISOString()}`],
+        { cwd: basePath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" },
+      );
+    } catch {
+      /* nothing to stash, or stash refused — proceed with reset */
+    }
+
     // Reset branch pointer and working tree to checkpoint SHA in one step.
     // Using `git reset --hard <sha>` works on the currently checked-out branch
     // (unlike `git branch -f` which is rejected for checked-out branches).

package/src/resources/extensions/gsd/safety/safety-harness.ts

@@ -25,6 +25,8 @@ export interface SafetyHarnessConfig {
   checkpoints: boolean;
   auto_rollback: boolean;
   timeout_scale_cap: number;
+  /** Glob patterns for files excluded from unexpected-change warnings (#4385). */
+  file_change_allowlist: string[];
 }
 
 // ─── Defaults ───────────────────────────────────────────────────────────────
@@ -39,6 +41,7 @@ const DEFAULTS: SafetyHarnessConfig = {
   checkpoints: true,
   auto_rollback: false,
   timeout_scale_cap: 6,
+  file_change_allowlist: [],
 };
 
 // ─── Public API ─────────────────────────────────────────────────────────────
@@ -62,6 +65,9 @@ export function resolveSafetyHarnessConfig(
     checkpoints: typeof raw.checkpoints === "boolean" ? raw.checkpoints : DEFAULTS.checkpoints,
     auto_rollback: typeof raw.auto_rollback === "boolean" ? raw.auto_rollback : DEFAULTS.auto_rollback,
     timeout_scale_cap: typeof raw.timeout_scale_cap === "number" ? raw.timeout_scale_cap : DEFAULTS.timeout_scale_cap,
+    file_change_allowlist: Array.isArray(raw.file_change_allowlist)
+      ? (raw.file_change_allowlist as unknown[]).filter((p): p is string => typeof p === "string")
+      : DEFAULTS.file_change_allowlist,
   };
 }
 
@@ -86,6 +92,9 @@ export {
   getFilePaths,
   recordToolCall,
   recordToolResult,
+  saveEvidenceToDisk,
+  loadEvidenceFromDisk,
+  clearEvidenceFromDisk,
 } from "./evidence-collector.js";
 
 export type { EvidenceEntry, BashEvidence, FileWriteEvidence, FileEditEvidence } from "./evidence-collector.js";

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

@@ -2,8 +2,8 @@
  * Service Tier — gating, status formatting, icon resolution, and
  * the /gsd fast command handler.
  *
- * Service tiers (priority/flex) are an OpenAI feature that only applies
- * to gpt-5.4 variants. This module centralizes the model-gating logic
+ * Service tiers (priority/flex) are an OpenAI feature that currently only
+ * applies to gpt-5.4 variants in GSD. This module centralizes the model-gating logic
  * so that icons, preferences, and the before_provider_request hook all
  * use a single source of truth.
  */
@@ -35,6 +35,9 @@ const SERVICE_TIER_SCOPE_NOTE = "Only affects gpt-5.4 models, regardless of prov
  * (set via CAPABILITY_PATCHES in packages/pi-ai/src/models.ts). When callers
  * have access to the full Model object, prefer reading capabilities directly.
  *
+ * GPT-5.5 is intentionally excluded until we verify its provider payload
+ * contract instead of assuming `service_tier` support.
+ *
  * See: https://github.com/gsd-build/gsd-2/issues/2546
  */
 const SERVICE_TIER_MODEL_PREFIXES = ["gpt-5.4"] as const;

package/src/resources/extensions/gsd/session-lock.ts

@@ -188,13 +188,14 @@ function ensureExitHandler(_gsdDir: string): void {
     // Lock files accumulate across main project .gsd/, worktree .gsd/,
     // and projects registry paths — cleanup must cover all of them.
     for (const dir of _lockDirRegistry) {
+      const lockFile = join(dir, LOCK_FILE);
+      const ownsRegisteredLock = isLockFileOwnedByCurrentProcess(lockFile);
       try {
-        const lockFile = join(dir, LOCK_FILE);
-        if (existsSync(lockFile)) unlinkSync(lockFile);
+        if (ownsRegisteredLock && existsSync(lockFile)) unlinkSync(lockFile);
       } catch { /* best-effort */ }
       try {
         const lockDir = join(dir + ".lock");
-        if (existsSync(lockDir)) rmSync(lockDir, { recursive: true, force: true });
+        if (ownsRegisteredLock && existsSync(lockDir)) rmSync(lockDir, { recursive: true, force: true });
       } catch { /* best-effort */ }
     }
   });
@@ -526,10 +527,13 @@ export function releaseSessionLock(basePath: string): void {
     _releaseFunction = null;
   }
 
-  // Remove the lock file at the current path
+  // Remove the lock file at the current path only if it still belongs to us.
+  // Lost-lock cleanup can run after another process has taken ownership; in
+  // that case deleting auto.lock would erase the newer owner's evidence.
   const lp = lockPath(basePath);
+  const ownsPrimaryLock = isLockFileOwnedByCurrentProcess(lp);
   try {
-    if (existsSync(lp)) unlinkSync(lp);
+    if (ownsPrimaryLock && existsSync(lp)) unlinkSync(lp);
   } catch {
     // Non-fatal
   }
@@ -540,12 +544,12 @@ export function releaseSessionLock(basePath: string): void {
   const lockTarget = effectiveLockTarget(gsdDir);
   try {
     const lockDir = join(lockTarget + ".lock");
-    if (existsSync(lockDir)) rmSync(lockDir, { recursive: true, force: true });
+    if (ownsPrimaryLock && existsSync(lockDir)) rmSync(lockDir, { recursive: true, force: true });
   } catch {
     // Non-fatal
   }
   // Also clean the per-milestone parallel directory itself if it exists
-  if (lockTarget !== gsdDir) {
+  if (ownsPrimaryLock && lockTarget !== gsdDir) {
     try {
       if (existsSync(lockTarget)) rmSync(lockTarget, { recursive: true, force: true });
     } catch {
@@ -556,13 +560,14 @@ export function releaseSessionLock(basePath: string): void {
   // Clean ALL registered lock paths (#1578) — lock files accumulate across
   // main project .gsd/, worktree .gsd/, and projects registry paths.
   for (const dir of _lockDirRegistry) {
+    const lockFile = join(dir, LOCK_FILE);
+    const ownsRegisteredLock = isLockFileOwnedByCurrentProcess(lockFile);
     try {
-      const lockFile = join(dir, LOCK_FILE);
-      if (existsSync(lockFile)) unlinkSync(lockFile);
+      if (ownsRegisteredLock && existsSync(lockFile)) unlinkSync(lockFile);
     } catch { /* best-effort */ }
     try {
       const lockDir = join(dir + ".lock");
-      if (existsSync(lockDir)) rmSync(lockDir, { recursive: true, force: true });
+      if (ownsRegisteredLock && existsSync(lockDir)) rmSync(lockDir, { recursive: true, force: true });
     } catch { /* best-effort */ }
   }
   _lockDirRegistry.clear();
@@ -619,6 +624,11 @@ function readExistingLockData(lp: string): SessionLockData | null {
   }
 }
 
+function isLockFileOwnedByCurrentProcess(lp: string): boolean {
+  const existing = readExistingLockData(lp);
+  return existing?.pid === process.pid;
+}
+
 /**
  * Retry-tolerant variant of readExistingLockData for use in onCompromised and
  * other paths where a transient filesystem hiccup (NFS/CIFS latency, macOS APFS

package/src/resources/extensions/gsd/skill-manifest.ts

@@ -0,0 +1,175 @@
+// GSD2 + skill-manifest — per-unit-type skill allowlist resolver (RFC #4779)
+//
+// Each auto-mode unit type can declare which skills are relevant to it. This
+// trims the set of skills considered for activation in the per-unit prompt,
+// reducing prompt token bloat and sharpening model focus.
+//
+// Contract:
+//   - Unknown unit types fall through to "all skills" (current behavior).
+//   - A manifest entry referencing a skill that is not installed is a silent
+//     no-op at filter time — the filter passes through installed skills only.
+//   - The allowlist is an inclusion list: only skills whose normalized name
+//     appears in the allowlist are retained. Order is not preserved.
+//
+// Phase 1 scope: seed manifests for a small number of unit types as proof.
+// Additional unit types can be added incrementally; each addition is a pure
+// data change with no wiring cost.
+
+import { logWarning } from "./workflow-logger.js";
+
+/** Normalize a skill reference the same way callers do (lowercase, trim). */
+function normalize(name: string): string {
+  return name.trim().toLowerCase();
+}
+
+/**
+ * Allowlist per unit type. Keys match unit type identifiers used by auto-mode
+ * dispatch. Values are normalized skill names.
+ *
+ * Wildcard semantics: a unit type absent from this map resolves to `null`
+ * (wildcard) — meaning "all installed skills are eligible". Prefer absence
+ * over an exhaustive list when uncertain.
+ */
+const UNIT_TYPE_SKILL_MANIFEST: Record<string, string[]> = {
+  // Milestone-level planning / meta flows — predictable skill sets.
+  "research-milestone": [
+    "write-docs",
+    "write-milestone-brief",
+    "decompose-into-slices",
+    "grill-me",
+    "design-an-interface",
+    "api-design",
+    "observability",
+  ],
+  "plan-milestone": [
+    "write-milestone-brief",
+    "decompose-into-slices",
+    "design-an-interface",
+    "grill-me",
+    "write-docs",
+    "api-design",
+    "tdd",
+    "verify-before-complete",
+  ],
+  "complete-milestone": [
+    "verify-before-complete",
+    "write-docs",
+    "handoff",
+    "forensics",
+    "observability",
+    "security-review",
+  ],
+  "validate-milestone": [
+    "verify-before-complete",
+    "review",
+    "test",
+    "lint",
+    "security-review",
+    "accessibility",
+    "forensics",
+    "observability",
+  ],
+  "reassess-roadmap": [
+    "decompose-into-slices",
+    "grill-me",
+    "write-milestone-brief",
+    "write-docs",
+    "forensics",
+  ],
+  // Slice-level research / planning.
+  "research-slice": [
+    "write-docs",
+    "decompose-into-slices",
+    "design-an-interface",
+    "grill-me",
+    "api-design",
+    "observability",
+  ],
+  "plan-slice": [
+    "decompose-into-slices",
+    "design-an-interface",
+    "grill-me",
+    "write-docs",
+    "api-design",
+    "tdd",
+    "verify-before-complete",
+  ],
+  "refine-slice": [
+    "decompose-into-slices",
+    "design-an-interface",
+    "grill-me",
+    "write-docs",
+    "api-design",
+    "tdd",
+    "verify-before-complete",
+  ],
+  "replan-slice": [
+    "decompose-into-slices",
+    "grill-me",
+    "design-an-interface",
+    "write-docs",
+    "api-design",
+  ],
+  "run-uat": [
+    "verify-before-complete",
+    "test",
+    "review",
+    "accessibility",
+  ],
+  // `execute-task` intentionally omitted — implementation hot path covers a
+  // wide surface of technologies; wildcard fallback preserves today's
+  // behavior until per-task skill hints can be derived from task-plan
+  // frontmatter. See RFC #4779.
+};
+
+/**
+ * Resolve the skill allowlist for a unit type.
+ *
+ * @returns Array of normalized skill names when an entry exists, or `null`
+ *   when the unit type is unknown (wildcard — caller should not filter).
+ */
+export function resolveSkillManifest(unitType: string | undefined): string[] | null {
+  if (!unitType) return null;
+  const entry = UNIT_TYPE_SKILL_MANIFEST[unitType];
+  if (!entry) return null;
+  return entry.map(normalize);
+}
+
+/**
+ * Filter a skill list by the manifest for `unitType`. Pass-through when the
+ * manifest is wildcard (unknown unit type) or `unitType` is undefined.
+ */
+export function filterSkillsByManifest<T extends { name: string }>(
+  skills: T[],
+  unitType: string | undefined,
+): T[] {
+  const allowlist = resolveSkillManifest(unitType);
+  if (allowlist === null) return skills;
+  const allowed = new Set(allowlist);
+  return skills.filter(skill => allowed.has(normalize(skill.name)));
+}
+
+/**
+ * Dev-mode guard: warn once per process if a manifest entry references a name
+ * that is not currently installed. Silent in production.
+ */
+const warnedMissing = new Set<string>();
+
+export function warnIfManifestHasMissingSkills(
+  unitType: string | undefined,
+  installedNames: Set<string>,
+): void {
+  // Strict mode is intentionally opt-in via exactly "1"; values like "0" or
+  // "false" must preserve the normal silent manifest behavior.
+  if (process.env.GSD_SKILL_MANIFEST_STRICT !== "1") return;
+  const allowlist = resolveSkillManifest(unitType);
+  if (!allowlist) return;
+  for (const name of allowlist) {
+    const key = `${unitType}:${name}`;
+    if (warnedMissing.has(key)) continue;
+    if (!installedNames.has(name)) {
+      warnedMissing.add(key);
+      logWarning("prompt", `skill-manifest: references uninstalled skill '${name}' for unit '${unitType}'`);
+    }
+  }
+}