gsd-pi 2.82.0-dev.ed17d078d → 3.0.0-dev.1b44e695b

package/src/resources/extensions/gsd/tools/validate-milestone.ts

@@ -15,6 +15,7 @@ import {
   transaction,
   insertAssessment,
   getMilestoneSlices,
+  getMilestone,
 } from "../gsd-db.js";
 import { resolveMilestonePath, clearPathCache } from "../paths.js";
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
@@ -53,6 +54,24 @@ export interface ValidateMilestoneOptions {
   turnId?: string;
 }
 
+function isVerificationNotApplicable(value: string): boolean {
+  const v = (value ?? "").toLowerCase().trim().replace(/[.\s]+$/, "");
+  if (!v || v === "none") return true;
+  return /^(?:none(?:[\s._\u2014-]+[\s\S]*)?|n\/?a(?:[\s._\u2014-]+[\s\S]*)?|not[\s._-]+(?:applicable|required|needed|provided)(?:[\s._\u2014-]+[\s\S]*)?|no[\s._-]+operational[\s\S]*)$/i.test(v);
+}
+
+function getRequiredVerificationClasses(milestoneId: string): string[] {
+  const milestone = getMilestone(milestoneId);
+  if (!milestone) return [];
+
+  const required: string[] = [];
+  if (!isVerificationNotApplicable(milestone.verification_contract)) required.push("Contract");
+  if (!isVerificationNotApplicable(milestone.verification_integration)) required.push("Integration");
+  if (!isVerificationNotApplicable(milestone.verification_operational)) required.push("Operational");
+  if (!isVerificationNotApplicable(milestone.verification_uat)) required.push("UAT");
+  return required;
+}
+
 function renderValidationMarkdown(params: ValidateMilestoneParams): string {
   let md = `---
 verdict: ${params.verdict}
@@ -99,6 +118,18 @@ export async function handleValidateMilestone(
   if (!isValidMilestoneVerdict(params.verdict)) {
     return { error: `verdict must be one of: ${VALIDATION_VERDICTS.join(", ")}` };
   }
+  const requiredClasses = getRequiredVerificationClasses(params.milestoneId);
+  if (requiredClasses.length > 0) {
+    const verificationClasses = params.verificationClasses ?? "";
+    const missingClass = requiredClasses.find(
+      (className) => !new RegExp(`\\b${className}\\b`, "i").test(verificationClasses),
+    );
+    if (missingClass) {
+      return {
+        error: `verificationClasses must include canonical row "${missingClass}" because this milestone planned ${missingClass.toLowerCase()} verification`,
+      };
+    }
+  }
 
   // ── Resolve paths and render markdown ────────────────────────────────
   // #4761: route through the canonical-root resolver so that when a live

package/src/resources/extensions/gsd/tools/workflow-tool-executors.ts

@@ -1,3 +1,6 @@
+// Project/App: GSD-2
+// File Purpose: Adapts shared GSD workflow handlers for MCP executor calls.
+
 import { ensureDbOpen } from "../bootstrap/dynamic-tools.js";
 import { sanitizeCompleteMilestoneParams } from "../bootstrap/sanitize-complete-milestone.js";
 import { loadWriteGateSnapshot, shouldBlockContextArtifactSaveInSnapshot, shouldBlockRootArtifactSaveInSnapshot } from "../bootstrap/write-gate.js";
@@ -25,6 +28,12 @@ import type { PlanSliceParams } from "./plan-slice.js";
 import { handlePlanSlice } from "./plan-slice.js";
 import type { ReplanSliceParams } from "./replan-slice.js";
 import { handleReplanSlice } from "./replan-slice.js";
+import type { ReopenMilestoneParams } from "./reopen-milestone.js";
+import { handleReopenMilestone } from "./reopen-milestone.js";
+import type { ReopenSliceParams } from "./reopen-slice.js";
+import { handleReopenSlice } from "./reopen-slice.js";
+import type { ReopenTaskParams } from "./reopen-task.js";
+import { handleReopenTask } from "./reopen-task.js";
 import type { ReassessRoadmapParams } from "./reassess-roadmap.js";
 import { handleReassessRoadmap } from "./reassess-roadmap.js";
 import type { ValidateMilestoneParams } from "./validate-milestone.js";
@@ -311,6 +320,9 @@ export type SliceCompleteExecutorParams = CompleteSliceParams;
 export type PlanMilestoneExecutorParams = PlanMilestoneParams;
 export type PlanSliceExecutorParams = PlanSliceParams;
 export type ReplanSliceExecutorParams = ReplanSliceParams;
+export type ReopenTaskExecutorParams = ReopenTaskParams;
+export type ReopenSliceExecutorParams = ReopenSliceParams;
+export type ReopenMilestoneExecutorParams = ReopenMilestoneParams;
 export type ValidateMilestoneExecutorParams = ValidateMilestoneParams;
 export type ReassessRoadmapExecutorParams = ReassessRoadmapParams;
 
@@ -371,6 +383,129 @@ export async function executeTaskComplete(
   }
 }
 
+export async function executeTaskReopen(
+  params: ReopenTaskExecutorParams,
+  basePath: string = process.cwd(),
+): Promise<ToolExecutionResult> {
+  const dbAvailable = await ensureDbOpen(basePath);
+  if (!dbAvailable) {
+    return {
+      content: [{ type: "text", text: "Error: GSD database is not available. Cannot reopen task." }],
+      details: { operation: "reopen_task", error: "db_unavailable" },
+      isError: true,
+    };
+  }
+  try {
+    const result = await handleReopenTask(params, basePath);
+    if ("error" in result) {
+      return {
+        content: [{ type: "text", text: `Error reopening task: ${result.error}` }],
+        details: { operation: "reopen_task", error: result.error },
+        isError: true,
+      };
+    }
+    return {
+      content: [{ type: "text", text: `Reopened task ${result.taskId} (${result.sliceId}/${result.milestoneId})` }],
+      details: {
+        operation: "reopen_task",
+        taskId: result.taskId,
+        sliceId: result.sliceId,
+        milestoneId: result.milestoneId,
+      },
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logError("tool", `reopen_task tool failed: ${msg}`, { tool: "gsd_task_reopen", error: String(err) });
+    return {
+      content: [{ type: "text", text: `Error reopening task: ${msg}` }],
+      details: { operation: "reopen_task", error: msg },
+      isError: true,
+    };
+  }
+}
+
+export async function executeSliceReopen(
+  params: ReopenSliceExecutorParams,
+  basePath: string = process.cwd(),
+): Promise<ToolExecutionResult> {
+  const dbAvailable = await ensureDbOpen(basePath);
+  if (!dbAvailable) {
+    return {
+      content: [{ type: "text", text: "Error: GSD database is not available. Cannot reopen slice." }],
+      details: { operation: "reopen_slice", error: "db_unavailable" },
+      isError: true,
+    };
+  }
+  try {
+    const result = await handleReopenSlice(params, basePath);
+    if ("error" in result) {
+      return {
+        content: [{ type: "text", text: `Error reopening slice: ${result.error}` }],
+        details: { operation: "reopen_slice", error: result.error },
+        isError: true,
+      };
+    }
+    return {
+      content: [{ type: "text", text: `Reopened slice ${result.sliceId} (${result.milestoneId})` }],
+      details: {
+        operation: "reopen_slice",
+        sliceId: result.sliceId,
+        milestoneId: result.milestoneId,
+        tasksReset: result.tasksReset,
+      },
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logError("tool", `reopen_slice tool failed: ${msg}`, { tool: "gsd_slice_reopen", error: String(err) });
+    return {
+      content: [{ type: "text", text: `Error reopening slice: ${msg}` }],
+      details: { operation: "reopen_slice", error: msg },
+      isError: true,
+    };
+  }
+}
+
+export async function executeMilestoneReopen(
+  params: ReopenMilestoneExecutorParams,
+  basePath: string = process.cwd(),
+): Promise<ToolExecutionResult> {
+  const dbAvailable = await ensureDbOpen(basePath);
+  if (!dbAvailable) {
+    return {
+      content: [{ type: "text", text: "Error: GSD database is not available. Cannot reopen milestone." }],
+      details: { operation: "reopen_milestone", error: "db_unavailable" },
+      isError: true,
+    };
+  }
+  try {
+    const result = await handleReopenMilestone(params, basePath);
+    if ("error" in result) {
+      return {
+        content: [{ type: "text", text: `Error reopening milestone: ${result.error}` }],
+        details: { operation: "reopen_milestone", error: result.error },
+        isError: true,
+      };
+    }
+    return {
+      content: [{ type: "text", text: `Reopened milestone ${result.milestoneId}` }],
+      details: {
+        operation: "reopen_milestone",
+        milestoneId: result.milestoneId,
+        slicesReset: result.slicesReset,
+        tasksReset: result.tasksReset,
+      },
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logError("tool", `reopen_milestone tool failed: ${msg}`, { tool: "gsd_milestone_reopen", error: String(err) });
+    return {
+      content: [{ type: "text", text: `Error reopening milestone: ${msg}` }],
+      details: { operation: "reopen_milestone", error: msg },
+      isError: true,
+    };
+  }
+}
+
 export async function executeSliceComplete(
   params: SliceCompleteExecutorParams,
   basePath: string = process.cwd(),
@@ -388,39 +523,53 @@ export async function executeSliceComplete(
       const m = s.match(/^(.+?)\s*(?:—|-)\s+(.+)$/);
       return m ? [m[1].trim(), m[2].trim()] : [s.trim(), ""];
     };
-    const wrapArray = (v: unknown): unknown[] =>
-      v == null ? [] : Array.isArray(v) ? v : [v];
-
-    const coerced = { ...params } as CompleteSliceParams & Record<string, unknown>;
-    coerced.provides = wrapArray(params.provides) as string[];
-    coerced.keyFiles = wrapArray(params.keyFiles) as string[];
-    coerced.keyDecisions = wrapArray(params.keyDecisions) as string[];
-    coerced.patternsEstablished = wrapArray(params.patternsEstablished) as string[];
-    coerced.observabilitySurfaces = wrapArray(params.observabilitySurfaces) as string[];
-    coerced.requirementsSurfaced = wrapArray(params.requirementsSurfaced) as string[];
-    coerced.drillDownPaths = wrapArray(params.drillDownPaths) as string[];
-    coerced.affects = wrapArray(params.affects) as string[];
-    coerced.filesModified = wrapArray(params.filesModified).map((f) => {
+    const wrapOptionalArray = (v: unknown): unknown[] | undefined =>
+      v == null ? undefined : Array.isArray(v) ? v : [v];
+    const coerced = Object.fromEntries(
+      Object.entries(params).filter(([, value]) => value !== undefined && value !== null),
+    ) as CompleteSliceParams & Record<string, unknown>;
+    const provides = wrapOptionalArray(params.provides);
+    if (provides !== undefined) coerced.provides = provides as string[];
+    const keyFiles = wrapOptionalArray(params.keyFiles);
+    if (keyFiles !== undefined) coerced.keyFiles = keyFiles as string[];
+    const keyDecisions = wrapOptionalArray(params.keyDecisions);
+    if (keyDecisions !== undefined) coerced.keyDecisions = keyDecisions as string[];
+    const patternsEstablished = wrapOptionalArray(params.patternsEstablished);
+    if (patternsEstablished !== undefined) coerced.patternsEstablished = patternsEstablished as string[];
+    const observabilitySurfaces = wrapOptionalArray(params.observabilitySurfaces);
+    if (observabilitySurfaces !== undefined) coerced.observabilitySurfaces = observabilitySurfaces as string[];
+    const requirementsSurfaced = wrapOptionalArray(params.requirementsSurfaced);
+    if (requirementsSurfaced !== undefined) coerced.requirementsSurfaced = requirementsSurfaced as string[];
+    const drillDownPaths = wrapOptionalArray(params.drillDownPaths);
+    if (drillDownPaths !== undefined) coerced.drillDownPaths = drillDownPaths as string[];
+    const affects = wrapOptionalArray(params.affects);
+    if (affects !== undefined) coerced.affects = affects as string[];
+    const filesModified = wrapOptionalArray(params.filesModified);
+    if (filesModified !== undefined) coerced.filesModified = filesModified.map((f) => {
       if (typeof f !== "string") return f;
       const [path, description] = splitPair(f);
       return { path, description };
     }) as Array<{ path: string; description: string }>;
-    coerced.requires = wrapArray(params.requires).map((r) => {
+    const requires = wrapOptionalArray(params.requires);
+    if (requires !== undefined) coerced.requires = requires.map((r) => {
       if (typeof r !== "string") return r;
       const [slice, provides] = splitPair(r);
       return { slice, provides };
     }) as Array<{ slice: string; provides: string }>;
-    coerced.requirementsAdvanced = wrapArray(params.requirementsAdvanced).map((r) => {
+    const requirementsAdvanced = wrapOptionalArray(params.requirementsAdvanced);
+    if (requirementsAdvanced !== undefined) coerced.requirementsAdvanced = requirementsAdvanced.map((r) => {
       if (typeof r !== "string") return r;
       const [id, how] = splitPair(r);
       return { id, how };
     }) as Array<{ id: string; how: string }>;
-    coerced.requirementsValidated = wrapArray(params.requirementsValidated).map((r) => {
+    const requirementsValidated = wrapOptionalArray(params.requirementsValidated);
+    if (requirementsValidated !== undefined) coerced.requirementsValidated = requirementsValidated.map((r) => {
       if (typeof r !== "string") return r;
       const [id, proof] = splitPair(r);
       return { id, proof };
     }) as Array<{ id: string; proof: string }>;
-    coerced.requirementsInvalidated = wrapArray(params.requirementsInvalidated).map((r) => {
+    const requirementsInvalidated = wrapOptionalArray(params.requirementsInvalidated);
+    if (requirementsInvalidated !== undefined) coerced.requirementsInvalidated = requirementsInvalidated.map((r) => {
       if (typeof r !== "string") return r;
       const [id, what] = splitPair(r);
       return { id, what };

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

@@ -106,7 +106,7 @@ export interface AuditWarning {
 export interface VerificationResult {
   passed: boolean; // true if all checks passed (or no checks discovered)
   checks: VerificationCheck[]; // per-command results
-  discoverySource: "preference" | "task-plan" | "package-json" | "none";
+  discoverySource: "preference" | "task-plan" | "package-json" | "python-project" | "node-test-file" | "none";
   timestamp: number; // Date.now() at gate start
   runtimeErrors?: RuntimeError[]; // optional — populated by captureRuntimeErrors()
   auditWarnings?: AuditWarning[]; // optional — populated by runDependencyAudit()

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

@@ -105,6 +105,7 @@ export interface ComposeContextModeInstructionOptions {
 const CONTEXT_MODE_LANE_LABELS: Record<Exclude<ContextModePolicy, "none">, string> = {
   interview: "interview",
   research: "research",
+  triage: "triage",
   planning: "planning",
   execution: "execution",
   verification: "verification",
@@ -117,6 +118,8 @@ const CONTEXT_MODE_GUIDANCE_BY_LANE: Record<Exclude<ContextModePolicy, "none">,
     "Use `gsd_resume` to restore prior discussion, `gsd_exec` for noisy discovery, and `gsd_exec_search` before repeating scans.",
   research:
     "Use `gsd_exec` for noisy research scans, `gsd_exec_search` before reruns, and `gsd_resume` to restore prior findings.",
+  triage:
+    "Use `gsd_resume` to restore prior triage context, `gsd_exec_search` to reuse evidence, and `gsd_exec` for noisy validation checks.",
   planning:
     "Use `gsd_resume` for planning continuity, `gsd_exec` for noisy checks, and `gsd_exec_search` before rerunning diagnostics.",
   execution:

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

@@ -99,7 +99,8 @@ export type ContextModePolicy =
   | "execution"
   | "verification"
   | "orchestration"
-  | "docs";
+  | "docs"
+  | "triage";
 
 /**
  * Tool-access policy per unit type (#4934).
@@ -132,6 +133,9 @@ export type ContextModePolicy =
  *                    the explicit `allowedPathGlobs` set; Bash safe-allowlist;
  *                    no subagents. Reserved for rewrite-docs, which legitimately
  *                    edits project markdown outside .gsd/.
+ *   - "verification"
+ *                  — Read tools + Bash for verification commands, writes
+ *                    restricted to .gsd/**, no subagents.
  *
  * The allowlist for "docs" is declared per-manifest rather than hardcoded so
  * projects with non-standard doc layouts can extend it without forking the
@@ -143,7 +147,8 @@ export type ToolsPolicy =
   | { readonly mode: "read-only" }
   | { readonly mode: "planning" }
   | { readonly mode: "planning-dispatch"; readonly allowedSubagents: readonly string[] }
-  | { readonly mode: "docs"; readonly allowedPathGlobs: readonly string[] };
+  | { readonly mode: "docs"; readonly allowedPathGlobs: readonly string[] }
+  | { readonly mode: "verification" };
 
 // ─── Computed-artifact registry (#4924 v2 contract) ───────────────────────
 
@@ -288,6 +293,7 @@ const COMMON_BUDGET_SMALL = 250_000;    // ~65K tokens
 
 const TOOLS_ALL: ToolsPolicy = { mode: "all" };
 const TOOLS_PLANNING: ToolsPolicy = { mode: "planning" };
+const TOOLS_VERIFICATION: ToolsPolicy = { mode: "verification" };
 // Like TOOLS_PLANNING but permits dispatch to read-only recon/planning
 // specialists. Runtime-enforced by write-gate.ts before the subagent tool runs.
 const TOOLS_PLANNING_DISPATCH_RECON: ToolsPolicy = {
@@ -338,6 +344,9 @@ export const KNOWN_UNIT_TYPES = [
   "run-uat",
   "gate-evaluate",
   "rewrite-docs",
+  // Sidecar units (triage, quick-task)
+  "triage-captures",
+  "quick-task",
   // Deep planning mode (project-level) units
   "workflow-preferences",
   "discuss-project",
@@ -404,11 +413,9 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     codebaseMap: false,
     preferences: "active-only",
     contextMode: "verification",
-    // planning-dispatch: validation is a verification-fan-out unit. It reads
-    // the milestone surface and dispatches reviewer/security/tester subagents
-    // to report findings without touching user source. Mirrors
-    // complete-milestone's policy. Write isolation to .gsd/ is preserved.
-    tools: TOOLS_PLANNING_DISPATCH_REVIEW,
+    // Validation may need to run shell verification commands and apply source
+    // fixes before milestone closeout can proceed.
+    tools: TOOLS_ALL,
     artifacts: {
       inline: ["roadmap", "slice-summary", "slice-uat", "requirements", "decisions", "templates"],
       excerpt: [],
@@ -423,11 +430,9 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     codebaseMap: false,
     preferences: "active-only",
     contextMode: "verification",
-    // planning-dispatch: completion is a high-leverage place to fan out to
-    // reviewer / security / tester subagents. They read the diff and report
-    // findings; they do not write user source. Write isolation to .gsd/ is
-    // preserved.
-    tools: TOOLS_PLANNING_DISPATCH_REVIEW,
+    // Milestone closeout must run unrestricted shell verification commands
+    // against the final diff before recording completion.
+    tools: TOOLS_ALL,
     artifacts: {
       // #4780 landed slice-summary as excerpt for this unit; phase 2 of
       // the architecture will read this manifest as the source of truth
@@ -447,7 +452,9 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     codebaseMap: true,
     preferences: "active-only",
     contextMode: "research",
-    tools: TOOLS_PLANNING,
+    // Multi-slice research dispatches use the research-slice unit contract to
+    // fan out scout subagents that write .gsd research artifacts.
+    tools: TOOLS_PLANNING_DISPATCH_RECON,
     artifacts: {
       inline: ["roadmap", "milestone-research", "dependency-summaries", "templates"],
       excerpt: [],
@@ -513,10 +520,9 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     codebaseMap: false,
     preferences: "active-only",
     contextMode: "verification",
-    // See complete-milestone — same rationale: dispatch to reviewer / security /
-    // tester subagents to fan out review work without bloating this unit's
-    // context.
-    tools: TOOLS_PLANNING_DISPATCH_REVIEW,
+    // Slice closeout may need to run shell verification commands and apply
+    // source fixes before completion can be recorded.
+    tools: TOOLS_ALL,
     artifacts: {
       // Phase 3 migration (#4782): matches today's actual
       // buildCompleteSlicePrompt inlining order. Overrides prepend +
@@ -587,7 +593,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     codebaseMap: false,
     preferences: "active-only",
     contextMode: "verification",
-    tools: TOOLS_PLANNING,
+    tools: TOOLS_VERIFICATION,
     artifacts: {
       // Phase 3 migration (#4782): manifest matches today's actual
       // buildRunUatPrompt inlining. Prior phase-1 entry listed
@@ -606,7 +612,9 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     codebaseMap: false,
     preferences: "active-only",
     contextMode: "verification",
-    tools: TOOLS_PLANNING,
+    // Gate evaluation fans out tester-style subagents, which read the slice
+    // plan and report via the DB-backed gate-result tool.
+    tools: TOOLS_PLANNING_DISPATCH_REVIEW,
     artifacts: {
       inline: ["slice-plan", "prior-task-summaries"],
       excerpt: [],
@@ -629,6 +637,36 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     },
     maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
   },
+  "triage-captures": {
+    skills: { mode: "all" },
+    knowledge: "scoped",
+    memory: "prompt-relevant",
+    codebaseMap: false,
+    preferences: "active-only",
+    contextMode: "triage",
+    tools: TOOLS_PLANNING,
+    artifacts: {
+      inline: ["roadmap", "slice-plan", "slice-summary", "requirements", "decisions", "templates"],
+      excerpt: [],
+      onDemand: [],
+    },
+    maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+  },
+  "quick-task": {
+    skills: { mode: "all" },
+    knowledge: "full",
+    memory: "prompt-relevant",
+    codebaseMap: true,
+    preferences: "active-only",
+    contextMode: "execution",
+    tools: TOOLS_ALL,
+    artifacts: {
+      inline: ["roadmap", "slice-plan", "task-plan", "requirements", "decisions", "templates"],
+      excerpt: [],
+      onDemand: [],
+    },
+    maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+  },
 
   // ─── Deep planning mode (project-level) units ────────────────────────
   // workflow-preferences: default-writing stage that records
@@ -734,3 +772,32 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
 export function resolveManifest(unitType: string): UnitContextManifest | null {
   return (UNIT_MANIFESTS as Record<string, UnitContextManifest>)[unitType] ?? null;
 }
+
+export interface SubagentPermissionContract {
+  readonly allowed: boolean;
+  readonly allowedSubagents: readonly string[];
+  readonly toolsMode: ToolsPolicy["mode"] | "unknown";
+}
+
+export function compileSubagentPermissionContract(
+  policy: ToolsPolicy | null | undefined,
+): SubagentPermissionContract {
+  if (!policy) {
+    return { allowed: false, allowedSubagents: [], toolsMode: "unknown" };
+  }
+  if (policy.mode === "all") {
+    return { allowed: true, allowedSubagents: ["*"], toolsMode: policy.mode };
+  }
+  if (policy.mode === "planning-dispatch") {
+    return {
+      allowed: true,
+      allowedSubagents: [...policy.allowedSubagents],
+      toolsMode: policy.mode,
+    };
+  }
+  return { allowed: false, allowedSubagents: [], toolsMode: policy.mode };
+}
+
+export function resolveSubagentPermissionContract(unitType: string): SubagentPermissionContract {
+  return compileSubagentPermissionContract(resolveManifest(unitType)?.tools);
+}

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

@@ -7,6 +7,27 @@ export function isNonEmptyString(value: unknown): value is string {
   return typeof value === "string" && value.trim().length > 0;
 }
 
+/**
+ * Characters that are used as delimiters in GSD state management documents
+ * and should not appear in milestone or slice titles.
+ */
+const TITLE_DELIMITER_RE = /[\u2014\u2013\/]/; // em dash, en dash, forward slash
+
+/**
+ * Check whether a milestone or slice title contains characters that conflict
+ * with GSD's state document delimiter conventions.
+ * Returns a human-readable description of the problem, or null if the title is safe.
+ */
+export function validateTitle(title: string): string | null {
+  if (TITLE_DELIMITER_RE.test(title)) {
+    const found: string[] = [];
+    if (/[\u2014\u2013]/.test(title)) found.push("em/en dash (\u2014 or \u2013)");
+    if (/\//.test(title)) found.push("forward slash (/)");
+    return `title contains ${found.join(" and ")}, which conflict with GSD state document delimiters`;
+  }
+  return null;
+}
+
 /**
  * Validate that `value` is an array of non-empty strings.
  * Throws with a message referencing `field` on failure.
@@ -14,7 +35,8 @@ export function isNonEmptyString(value: unknown): value is string {
  */
 export function validateStringArray(value: unknown, field: string): string[] {
   if (!Array.isArray(value)) {
-    throw new Error(`${field} must be an array`);
+    const received = value === null ? "null" : typeof value;
+    throw new Error(`${field} must be an array of strings, not ${received}`);
   }
   if (value.some((item) => !isNonEmptyString(item))) {
     throw new Error(`${field} must contain only non-empty strings`);