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

package/dist/resources/extensions/gsd/milestone-scope-classifier.js

@@ -0,0 +1,299 @@
+// GSD-2 — Milestone scope classifier (#4781 / ADR-003 companion).
+//
+// Pure heuristics over milestone planning fields. Produces a PipelineVariant
+// that downstream dispatch logic can use to shape the auto-mode sequence.
+// No LLM calls, no file I/O, sub-millisecond.
+//
+// Distinct from `complexity-classifier.ts`, which decides *model tier*
+// (light/standard/heavy) for an individual unit. This module decides
+// *pipeline topology* for an entire milestone at plan-milestone time.
+//
+// This file ships the classifier in isolation. Dispatch-side wiring
+// lands in follow-up PRs so the classification contract can be reviewed
+// and tested before any behavior change reaches users.
+// ─── Keyword sets ─────────────────────────────────────────────────────────
+/**
+ * Override keywords that force `standard` (at minimum) regardless of
+ * apparent triviality. Presence of any of these signals work that is
+ * either security-sensitive, irreversible, or requires runtime verification
+ * a "trivial" pipeline would skip.
+ *
+ * Matched as case-insensitive word-boundary substrings. Conservative — err
+ * on the side of including a keyword; over-classifying to `standard` costs
+ * units, under-classifying could ship broken auth/security/migration work.
+ */
+const OVERRIDE_KEYWORDS = [
+    // Security-sensitive
+    "security", "auth", "authn", "authz", "authentication", "authorization",
+    "credential", "secret", "password", "token", "oauth", "encrypt", "decrypt",
+    "vulnerability", "exploit", "permission", "rbac", "acl",
+    // Data-migration / irreversible
+    "migration", "migrate", "schema change", "data migration",
+    "backfill", "drop column", "drop table",
+    // Compliance / regulatory
+    "compliance", "gdpr", "hipaa", "soc2", "pci",
+    // Infra / deploy — runtime verification needed
+    "deploy", "rollout", "canary", "production database",
+];
+/**
+ * Keywords that contribute to `complex` classification on their own.
+ * Different from OVERRIDE_KEYWORDS in that a single match bumps to
+ * complex, not just to standard.
+ */
+const COMPLEX_KEYWORDS = [
+    "multi-service", "distributed", "consensus", "saga", "eventual consistency",
+    "breaking change", "api contract change", "schema redesign",
+    "architect", "architecture", "refactor core",
+];
+/**
+ * Trivial-signal keywords: presence strongly suggests a simple, contained
+ * deliverable. Only effective when combined with low file count / no tests
+ * / no override keywords.
+ */
+const TRIVIAL_KEYWORDS = [
+    "single file", "one file", "static html", "static page",
+    "one-page", "landing page", "readme", "docs only", "typo", "rename",
+    "spelling", "comment", "changelog",
+    // Browser-only / no-build deliverable shapes (b23 forensic case).
+    "pure html", "browser-based", "no build step", "no build tooling",
+    "localstorage", "client-only", "no backend", "no server", "no backend.",
+];
+// ─── Heuristics ───────────────────────────────────────────────────────────
+/**
+ * Estimate how many distinct files the milestone will touch, based on
+ * explicit mentions in the input text. Returns `null` when no hint is
+ * discoverable — callers should treat that as "unknown, no signal."
+ */
+function extractFileCountHint(text) {
+    // Explicit phrasing: "a single file", "two files", "3 files"
+    const singleFileMatch = /\b(a|one|single)\s+(file|page)\b/i.test(text);
+    if (singleFileMatch)
+        return 1;
+    const digitMatch = text.match(/\b(\d+)\s+files?\b/i);
+    if (digitMatch) {
+        const n = parseInt(digitMatch[1], 10);
+        if (!Number.isNaN(n))
+            return n;
+    }
+    const wordMatch = text.match(/\b(two|three|four|five|six|seven|eight|nine|ten)\s+files?\b/i);
+    if (wordMatch) {
+        const wordMap = {
+            two: 2, three: 3, four: 4, five: 5,
+            six: 6, seven: 7, eight: 8, nine: 9, ten: 10,
+        };
+        return wordMap[wordMatch[1].toLowerCase()] ?? null;
+    }
+    return null;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function containsAnyKeyword(haystack, keywords) {
+    const lower = haystack.toLowerCase();
+    const hits = [];
+    for (const kw of keywords) {
+        // Word-boundary match to prevent substring collisions (e.g. "auth"
+        // must not match "author", "api" must not match "capital"). Phrases
+        // containing non-word characters (hyphens, slashes) still work because
+        // `\b` sits at the word-char / non-word-char transition, so
+        // `\bbrowser-based\b` matches "browser-based" bounded by whitespace
+        // or punctuation on either side.
+        const pattern = new RegExp(String.raw `\b${escapeRegExp(kw)}\b`, "i");
+        if (pattern.test(lower))
+            hits.push(kw);
+    }
+    return hits;
+}
+/**
+ * True when `term` appears in the text without an immediately preceding
+ * negator (no / without / not / zero / skip) in the same clause. Used to
+ * keep phrases like "no backend" or "no tests" from flipping a trivial-
+ * class milestone to standard. Best-effort; imperfect English parsing,
+ * biased toward false negatives (if unsure, treats term as present —
+ * which routes to standard, the safe pipeline).
+ */
+function mentionsWithoutNegation(text, term) {
+    const lower = text.toLowerCase();
+    const termPattern = new RegExp(String.raw `\b${term}\b`, "gi");
+    const matches = Array.from(lower.matchAll(termPattern));
+    for (const m of matches) {
+        const start = m.index ?? 0;
+        const windowStart = Math.max(0, start - 30);
+        const window = lower.slice(windowStart, start);
+        // Negator anywhere in the 30-char lookback window counts as negation —
+        // covers "no backend", "without a server", "not using api", "zero
+        // dependencies on an api". If a sentence break intervenes between the
+        // negator and the term, treat as a different clause (positive mention).
+        const hasNegator = /(^|[^a-z0-9])(no|without|not|zero|skip(s|ping)?|drops?)\b/i.test(window);
+        const hasSentenceBreak = /[.;!?]/.test(window);
+        if (hasNegator && !hasSentenceBreak)
+            continue;
+        return true;
+    }
+    return false;
+}
+function mentionsTests(haystack) {
+    return mentionsWithoutNegation(haystack, "test")
+        || mentionsWithoutNegation(haystack, "tests")
+        || mentionsWithoutNegation(haystack, "testing")
+        || mentionsWithoutNegation(haystack, "spec")
+        || mentionsWithoutNegation(haystack, "unit test")
+        || mentionsWithoutNegation(haystack, "integration test");
+}
+function mentionsBackend(haystack) {
+    return mentionsWithoutNegation(haystack, "api")
+        || mentionsWithoutNegation(haystack, "backend")
+        || mentionsWithoutNegation(haystack, "server")
+        || mentionsWithoutNegation(haystack, "database")
+        || mentionsWithoutNegation(haystack, "endpoint");
+}
+// ─── DB adapter ───────────────────────────────────────────────────────────
+/**
+ * Shape adapter: convert a milestone DB row into the classifier input
+ * object. Keeps `milestone-scope-classifier.ts` free of DB types at the
+ * module boundary — callers can either use this helper or hand-build the
+ * input themselves (e.g. from plan-milestone tool params before insert).
+ */
+export function milestoneRowToScopeInput(row) {
+    return {
+        title: row.title,
+        vision: row.vision,
+        successCriteria: row.success_criteria,
+        keyRisks: row.key_risks,
+        definitionOfDone: row.definition_of_done,
+        requirementCoverage: row.requirement_coverage,
+        verificationContract: row.verification_contract,
+        verificationIntegration: row.verification_integration,
+        verificationOperational: row.verification_operational,
+        verificationUat: row.verification_uat,
+    };
+}
+/**
+ * Compute the pipeline variant for a milestone by reading its planning
+ * fields from the DB and running the classifier. Returns `null` when
+ * classification is unavailable (DB closed, milestone missing, unexpected
+ * error) — callers MUST treat null as "run the full pipeline" so a
+ * classification failure never silently downshifts dispatch.
+ */
+export async function getMilestonePipelineVariant(mid) {
+    try {
+        const { isDbAvailable, getMilestone } = await import("./gsd-db.js");
+        if (!isDbAvailable())
+            return null;
+        const row = getMilestone(mid);
+        if (!row)
+            return null;
+        return classifyMilestoneScope(milestoneRowToScopeInput(row)).variant;
+    }
+    catch {
+        return null;
+    }
+}
+// ─── Public API ───────────────────────────────────────────────────────────
+/**
+ * Classify a milestone's pipeline variant based on its planning inputs.
+ *
+ * Precedence (matches implementation order — complex-first so that
+ * security-sensitive architecture refactors correctly route to complex
+ * rather than standard; the override hit is still recorded in
+ * `signals.triggeredOverride` for telemetry):
+ *  1. Complex-signal keyword OR ≥ 8 file hint OR architecture/refactor-core
+ *     language → `complex`.
+ *  2. Override keyword → `standard` (at minimum). Prevents trivial
+ *     misclassification of security / auth / migration work.
+ *  3. Trivial-signal keyword AND ≤ 2 file hint AND no tests mentioned AND
+ *     no backend mentioned → `trivial`.
+ *  4. Otherwise → `standard`.
+ *
+ * Ambiguity → `standard` (today's default). Safe to run the full pipeline.
+ */
+export function classifyMilestoneScope(input) {
+    const haystack = [
+        input.title ?? "",
+        input.vision ?? "",
+        (input.successCriteria ?? []).join("\n"),
+        (input.keyRisks ?? []).map(r => `${r.risk ?? ""} ${r.whyItMatters ?? ""}`).join("\n"),
+        (input.definitionOfDone ?? []).join("\n"),
+        input.requirementCoverage ?? "",
+        input.verificationContract ?? "",
+        input.verificationIntegration ?? "",
+        input.verificationOperational ?? "",
+        input.verificationUat ?? "",
+    ].join("\n");
+    const overrideHits = containsAnyKeyword(haystack, OVERRIDE_KEYWORDS);
+    const complexHits = containsAnyKeyword(haystack, COMPLEX_KEYWORDS);
+    const trivialHits = containsAnyKeyword(haystack, TRIVIAL_KEYWORDS);
+    const fileCountHint = extractFileCountHint(haystack);
+    const hasTests = mentionsTests(haystack);
+    const hasBackend = mentionsBackend(haystack);
+    const reasons = [];
+    // Rule 2: complex-class signals. Evaluated before override because a
+    // complex + override input should land in complex, not standard.
+    if (complexHits.length > 0) {
+        reasons.push(`complex keywords: ${complexHits.slice(0, 3).join(", ")}`);
+    }
+    if (fileCountHint !== null && fileCountHint >= 8) {
+        reasons.push(`file count hint: ${fileCountHint}`);
+    }
+    const isComplex = complexHits.length > 0 || (fileCountHint !== null && fileCountHint >= 8);
+    if (isComplex) {
+        return {
+            variant: "complex",
+            reasons,
+            signals: {
+                triggeredOverride: overrideHits.length > 0,
+                complexCount: complexHits.length,
+                trivialCount: trivialHits.length,
+                fileCountHint,
+            },
+        };
+    }
+    // Rule 1: override keywords force standard.
+    if (overrideHits.length > 0) {
+        return {
+            variant: "standard",
+            reasons: [`override keywords: ${overrideHits.slice(0, 3).join(", ")}`],
+            signals: {
+                triggeredOverride: true,
+                complexCount: complexHits.length,
+                trivialCount: trivialHits.length,
+                fileCountHint,
+            },
+        };
+    }
+    // Rule 3: trivial signals — require ALL of: trivial-keyword, low file
+    // hint (or nothing suggesting high count), no test mention, no backend
+    // mention.
+    const fileCountOk = fileCountHint === null || fileCountHint <= 2;
+    const trivial = trivialHits.length > 0 &&
+        fileCountOk &&
+        !hasTests &&
+        !hasBackend;
+    if (trivial) {
+        reasons.push(`trivial keywords: ${trivialHits.slice(0, 3).join(", ")}`);
+        if (fileCountHint !== null)
+            reasons.push(`file count hint: ${fileCountHint}`);
+        reasons.push("no tests mentioned", "no backend mentioned");
+        return {
+            variant: "trivial",
+            reasons,
+            signals: {
+                triggeredOverride: false,
+                complexCount: complexHits.length,
+                trivialCount: trivialHits.length,
+                fileCountHint,
+            },
+        };
+    }
+    // Rule 4: fallback.
+    return {
+        variant: "standard",
+        reasons: reasons.length > 0 ? reasons : ["no strong signals — default"],
+        signals: {
+            triggeredOverride: overrideHits.length > 0,
+            complexCount: complexHits.length,
+            trivialCount: trivialHits.length,
+            fileCountHint,
+        },
+    };
+}

package/dist/resources/extensions/gsd/model-cost-table.js

@@ -43,6 +43,9 @@ export const BUNDLED_COST_TABLE = [
     { id: "gpt-5.3-codex-spark", inputPer1k: 0.0003, outputPer1k: 0.0012, updatedAt: "2026-03-29" },
     { id: "gpt-5.4", inputPer1k: 0.005, outputPer1k: 0.02, updatedAt: "2026-03-29" },
     { id: "gpt-5.4-mini", inputPer1k: 0.00075, outputPer1k: 0.0045, updatedAt: "2026-04-18" },
+    // GPT-5.5 API list price, also used for live Codex OAuth routing.
+    // Source: https://openai.com/api/pricing/
+    { id: "gpt-5.5", inputPer1k: 0.005, outputPer1k: 0.03, updatedAt: "2026-04-23" },
     // Google
     { id: "gemini-2.0-flash", inputPer1k: 0.0001, outputPer1k: 0.0004, updatedAt: "2025-03-15" },
     { id: "gemini-flash-2.0", inputPer1k: 0.0001, outputPer1k: 0.0004, updatedAt: "2025-03-15" },

package/dist/resources/extensions/gsd/model-router.js

@@ -43,6 +43,7 @@ export const MODEL_CAPABILITY_TIER = {
     "gpt-5.2-codex": "heavy",
     "gpt-5.3-codex": "heavy",
     "gpt-5.4": "heavy",
+    "gpt-5.5": "heavy",
     "o1": "heavy",
     "o3": "heavy",
     "o4-mini": "heavy",
@@ -76,6 +77,7 @@ const MODEL_COST_PER_1K_INPUT = {
     "gpt-5.3-codex": 0.005,
     "gpt-5.3-codex-spark": 0.0003,
     "gpt-5.4": 0.005,
+    "gpt-5.5": 0.005,
     "o4-mini": 0.005,
     "o4-mini-deep-research": 0.005,
     "gemini-2.0-flash": 0.0001,
@@ -116,6 +118,10 @@ export const MODEL_CAPABILITY_PROFILES = {
     "gpt-5.3-codex": { coding: 94, debugging: 91, research: 74, reasoning: 89, speed: 50, longContext: 80, instruction: 89 },
     "gpt-5.3-codex-spark": { coding: 68, debugging: 58, research: 42, reasoning: 52, speed: 90, longContext: 50, instruction: 74 },
     "gpt-5.4": { coding: 95, debugging: 92, research: 88, reasoning: 94, speed: 42, longContext: 88, instruction: 92 },
+    // GPT-5.5 scores are relative to the existing gpt-5.4 profile and backed by
+    // OpenAI's 2026-04-23 published eval deltas across coding, tool use, and long context.
+    // Source: https://openai.com/index/introducing-gpt-5-5/
+    "gpt-5.5": { coding: 96, debugging: 93, research: 89, reasoning: 95, speed: 42, longContext: 90, instruction: 93 },
     // ── OpenAI o-series (reasoning-first) ──────────────────────────────────────
     "o1": { coding: 78, debugging: 82, research: 78, reasoning: 90, speed: 20, longContext: 65, instruction: 82 },
     "o3": { coding: 80, debugging: 85, research: 80, reasoning: 92, speed: 25, longContext: 70, instruction: 85 },

package/dist/resources/extensions/gsd/preferences-validation.js

@@ -1031,6 +1031,29 @@ export function validatePreferences(preferences) {
         if (g.merge_to_main !== undefined) {
             warnings.push("git.merge_to_main is deprecated — milestone-level merge is now always used. Remove this setting.");
         }
+        // #4765 — collapse cadence + milestone resquash
+        if (g.collapse_cadence !== undefined) {
+            const validCadence = new Set(["milestone", "slice"]);
+            if (typeof g.collapse_cadence === "string" && validCadence.has(g.collapse_cadence)) {
+                git.collapse_cadence = g.collapse_cadence;
+            }
+            else {
+                errors.push("git.collapse_cadence must be one of: milestone, slice");
+            }
+        }
+        if (g.milestone_resquash !== undefined) {
+            if (typeof g.milestone_resquash === "boolean") {
+                git.milestone_resquash = g.milestone_resquash;
+                const cadence = git.collapse_cadence
+                    ?? (typeof g.collapse_cadence === "string" ? g.collapse_cadence : undefined);
+                if (cadence !== "slice") {
+                    warnings.push('git.milestone_resquash is ignored unless git.collapse_cadence is "slice"');
+                }
+            }
+            else {
+                errors.push("git.milestone_resquash must be a boolean");
+            }
+        }
         if (Object.keys(git).length > 0) {
             validated.git = git;
         }

package/dist/resources/extensions/gsd/prompt-cache-optimizer.js

@@ -24,6 +24,10 @@ const SEMI_STATIC_LABELS = new Set([
     "prior-summaries",
     "project-context",
     "overrides",
+    // KNOWLEDGE is milestone-scoped (stable within a session), so it belongs
+    // in the cacheable prefix. See issue #4719.
+    "knowledge",
+    "project-knowledge",
 ]);
 /** Labels that change per-task */
 const DYNAMIC_LABELS = new Set([

package/dist/resources/extensions/gsd/prompts/complete-milestone.md

@@ -10,7 +10,11 @@ Your working directory is `{{workingDirectory}}`. All file reads, writes, and sh
 
 All slices are done. You are closing out the milestone — verifying that the assembled work actually delivers the promised outcome, writing the milestone summary, and updating project state. The milestone summary is the final record. After you finish, the system merges the worktree back to the integration branch. If there are queued milestones, the next one starts its own research → plan → execute cycle from a clean slate — the milestone summary is how it learns what was already built.
 
-All relevant context has been preloaded below — the roadmap, all slice summaries, requirements, decisions, and project context are inlined. Start working immediately without re-reading these files.
+Preloaded context below — the roadmap, compact slice-summary excerpts, requirements, decisions, and project context. **Slice summaries are excerpts, not full files.** They include frontmatter fields, section heads (deviations, known limitations, follow-ups), and short narrative only. When drafting LEARNINGS, the Decision Re-evaluation table, or cross-slice narrative, Read the full slice SUMMARY.md files listed under "On-demand Slice Summaries" — do that selectively as needed, not preemptively.
+
+Start with what the excerpts give you. Read full files when the section heads signal richer context you need.
+
+**On-demand Read ordering:** Complete all slice SUMMARY Reads you need for cross-slice synthesis, the Decision Re-evaluation table, and LEARNINGS **before** calling `gsd_complete_milestone` (step 10). Once that tool runs, the milestone is marked complete in the DB — running out of tool budget between step 10 and the LEARNINGS write (step 12) leaves the milestone committed without its LEARNINGS artifact.
 
 {{inlinedContext}}
 

package/dist/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
 

package/dist/resources/extensions/gsd/service-tier.js

@@ -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.
  */
@@ -21,6 +21,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"];

package/dist/resources/extensions/gsd/skill-manifest.js

@@ -0,0 +1,168 @@
+// 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) {
+    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 = {
+    // 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) {
+    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(skills, unitType) {
+    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();
+export function warnIfManifestHasMissingSkills(unitType, installedNames) {
+    // 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}'`);
+        }
+    }
+}