gsd-pi 2.82.0-dev.ed17d078d → 3.0.0

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

@@ -132,6 +132,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 +146,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 +292,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 = {
@@ -406,8 +411,8 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     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.
+    // to report findings without touching user source. Write isolation to
+    // .gsd/ is preserved.
     tools: TOOLS_PLANNING_DISPATCH_REVIEW,
     artifacts: {
       inline: ["roadmap", "slice-summary", "slice-uat", "requirements", "decisions", "templates"],
@@ -423,11 +428,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 +450,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: [],
@@ -587,7 +592,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 +611,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: [],
@@ -734,3 +741,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`);

package/src/resources/extensions/gsd/verification-gate.ts

@@ -4,7 +4,7 @@
 // First non-empty source wins.
 
 import { spawnSync, type SpawnSyncReturns } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, type Dirent } from "node:fs";
 import { join, basename } from "node:path";
 import type { AuditWarning, RuntimeError, VerificationCheck, VerificationResult } from "./types.js";
 import { DEFAULT_COMMAND_TIMEOUT_MS } from "./constants.js";
@@ -44,7 +44,8 @@ const PACKAGE_SCRIPT_KEYS = ["typecheck", "lint", "test"] as const;
  *   1. Explicit preference commands
  *   2. Task plan verify field (split on &&)
  *   3. package.json scripts (typecheck, lint, test)
- *   4. None found
+ *   4. Python pytest project markers
+ *   5. None found
  */
 export function discoverCommands(options: DiscoverCommandsOptions): DiscoveredCommands {
   // 1. Preference commands
@@ -91,10 +92,67 @@ export function discoverCommands(options: DiscoverCommandsOptions): DiscoveredCo
     }
   }
 
-  // 4. Nothing found
+  const pythonCommand = discoverPythonPytestCommand(options.cwd);
+  if (pythonCommand) {
+    return { commands: [pythonCommand], source: "python-project" };
+  }
+
+  // 5. Nothing found
   return { commands: [], source: "none" };
 }
 
+function discoverPythonPytestCommand(cwd: string): string | null {
+  const hasPythonTestFiles = hasPythonTests(join(cwd, "tests"));
+  const hasPytestConfig = existsSync(join(cwd, "pytest.ini"));
+  const pyprojectPath = join(cwd, "pyproject.toml");
+  const hasPyproject = existsSync(pyprojectPath);
+
+  if (!hasPythonTestFiles && !hasPytestConfig && !hasPyproject) {
+    return null;
+  }
+
+  if (hasPytestConfig || hasPythonTestFiles) {
+    return "python3 -m pytest";
+  }
+
+  try {
+    const pyproject = readFileSync(pyprojectPath, "utf-8");
+    if (
+      pyproject.includes("[tool.pytest]") ||
+      pyproject.includes("[tool.pytest.") ||
+      pyproject.includes("[pytest]") ||
+      pyproject.includes("[tool:pytest]")
+    ) {
+      return "python3 -m pytest";
+    }
+  } catch {
+    // Ignore unreadable pyproject.toml and fall through.
+  }
+
+  return null;
+}
+
+function hasPythonTests(dir: string): boolean {
+  let entries: Dirent[];
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+
+  for (const entry of entries) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory() && hasPythonTests(path)) {
+      return true;
+    }
+    if (entry.isFile() && /^test_.*\.py$|^.*_test\.py$/.test(entry.name)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
 // ─── Failure Context Formatting ──────────────────────────────────────────────
 
 /** Maximum chars of stderr to include per failed check in failure context. */
@@ -144,7 +202,7 @@ export function formatFailureContext(result: VerificationResult): string {
 // ─── Gate Execution ─────────────────────────────────────────────────────────
 
 /** Characters that indicate shell injection when found in a command string. */
-const SHELL_INJECTION_PATTERN = /[;|`]|\$\(/;
+const SHELL_INJECTION_PATTERN = /[;|`<>]|\$\(/;
 
 /**
  * Known executable first-tokens that are safe to run.
@@ -182,6 +240,7 @@ const KNOWN_COMMAND_PREFIXES = new Set([
  * Heuristics (any true → prose-like):
  *   1. First token starts with an uppercase letter and the string has 4+ words
  *   2. String contains commas followed by spaces (prose clause structure)
+ *   3. First token has no ASCII letters or digits and the string has 4+ words
  */
 export function isLikelyCommand(cmd: string): boolean {
   const trimmed = cmd.trim();
@@ -208,6 +267,9 @@ export function isLikelyCommand(cmd: string): boolean {
   // First token has uppercase letters and no path separators → prose
   if (/[A-Z]/.test(firstToken) && !firstToken.includes("/")) return false;
 
+  // Non-ASCII prose with multiple words should not be executed as a command.
+  if (!/[A-Za-z0-9]/.test(firstToken) && tokens.length >= 4) return false;
+
   return true;
 }
 
@@ -215,9 +277,19 @@ export function isLikelyCommand(cmd: string): boolean {
  * Validate a command string for obvious shell injection patterns.
  * Returns the command unchanged if safe, or null if suspicious.
  */
+export function validateVerificationCommand(cmd: string): { ok: true } | { ok: false; reason: string } {
+  if (SHELL_INJECTION_PATTERN.test(cmd)) {
+    return { ok: false, reason: "contains shell control syntax such as pipes, redirects, semicolons, backticks, or command substitution" };
+  }
+  if (!isLikelyCommand(cmd)) {
+    return { ok: false, reason: "does not look like a runnable command" };
+  }
+  return { ok: true };
+}
+
 function sanitizeCommand(cmd: string): string | null {
-  if (SHELL_INJECTION_PATTERN.test(cmd)) return null;
-  if (!isLikelyCommand(cmd)) return null;
+  const validation = validateVerificationCommand(cmd);
+  if (!validation.ok) return null;
   return cmd;
 }
 

package/src/resources/extensions/gsd/verification-verdict.ts

@@ -0,0 +1,47 @@
+// Project/App: GSD-2
+// File Purpose: Host-owned verification verdict policy for auto-mode units.
+
+import type { VerificationResult as VerificationGateResult } from "./types.js";
+
+export type VerificationVerdictReason =
+  | "passed"
+  | "no-host-checks"
+  | "checks-failed";
+
+export interface VerificationVerdict {
+  passed: boolean;
+  reason: VerificationVerdictReason;
+  retryable: boolean;
+  failureContext: string;
+}
+
+export function decideVerificationVerdict(
+  unitType: string,
+  result: VerificationGateResult,
+): VerificationVerdict {
+  if (unitType === "execute-task" && result.discoverySource === "none" && result.checks.length === 0) {
+    return {
+      passed: false,
+      reason: "no-host-checks",
+      retryable: false,
+      failureContext:
+        "No runnable host-owned verification command was discovered. Add project verification_commands or a runnable task-plan Verify command before completing this execute-task.",
+    };
+  }
+
+  if (!result.passed) {
+    return {
+      passed: false,
+      reason: "checks-failed",
+      retryable: true,
+      failureContext: "",
+    };
+  }
+
+  return {
+    passed: true,
+    reason: "passed",
+    retryable: false,
+    failureContext: "",
+  };
+}

package/src/resources/extensions/gsd/workflow-mcp.ts

@@ -18,6 +18,7 @@ export interface WorkflowCapabilityOptions {
   unitType?: string;
   authMode?: "apiKey" | "oauth" | "externalCli" | "none";
   baseUrl?: string;
+  activeTools?: string[];
 }
 
 const MCP_WORKFLOW_TOOL_SURFACE = new Set([
@@ -383,6 +384,15 @@ function hasAskUserQuestionsTool(activeTools: string[]): boolean {
   });
 }
 
+function hasRequiredTool(requiredTool: string, activeTools: string[]): boolean {
+  return activeTools.some((toolName) => {
+    if (toolName === requiredTool) return true;
+    if (!toolName.startsWith("mcp__")) return false;
+    const toolSeparator = toolName.indexOf("__", "mcp__".length);
+    return toolSeparator >= 0 && toolName.slice(toolSeparator + 2) === requiredTool;
+  });
+}
+
 function workflowMcpStructuredQuestionsOptIn(env: NodeJS.ProcessEnv = process.env): boolean {
   const value = env.GSD_WORKFLOW_MCP_STRUCTURED_QUESTIONS;
   return value === "1" || value === "true";
@@ -423,8 +433,15 @@ export function getWorkflowTransportSupportError(
     return `Provider ${providerLabel} cannot run ${surface}${unitLabel}: the GSD workflow MCP server is not configured or discoverable. Detected Claude Code model but no workflow MCP. Please run /gsd mcp init . from your project root. You can also configure GSD_WORKFLOW_MCP_COMMAND, build packages/mcp-server/dist/cli.js, or install gsd-mcp-server on PATH.`;
   }
 
-  const missing = [...new Set(requiredTools)].filter((tool) => !MCP_WORKFLOW_TOOL_SURFACE.has(tool));
+  const uniqueRequired = [...new Set(requiredTools)];
+  const missing = (options.activeTools && options.activeTools.length > 0)
+    ? uniqueRequired.filter((tool) => !hasRequiredTool(tool, options.activeTools!))
+    : uniqueRequired.filter((tool) => !MCP_WORKFLOW_TOOL_SURFACE.has(tool));
   if (missing.length === 0) return null;
 
+  if (options.activeTools && options.activeTools.length > 0) {
+    return `Provider ${providerLabel} cannot run ${surface}${unitLabel}: this unit requires ${missing.join(", ")}, but the active runtime toolset currently exposes only ${options.activeTools.slice().sort().join(", ")}.`;
+  }
+
   return `Provider ${providerLabel} cannot run ${surface}${unitLabel}: this unit requires ${missing.join(", ")}, but the workflow MCP transport currently exposes only ${Array.from(MCP_WORKFLOW_TOOL_SURFACE).sort().join(", ")}.`;
 }

package/src/resources/extensions/gsd/workflow-projections.ts

@@ -195,11 +195,11 @@ export function renderSummaryContent(
 
   // ── Frontmatter (YAML list format, matches parseSummary() expectations) ──
   const keyFilesYaml = taskRow.key_files && taskRow.key_files.length > 0
-    ? taskRow.key_files.map(f => `  - ${f}`).join("\n")
-    : "  - (none)";
+    ? `\n${taskRow.key_files.map(f => `  - ${f}`).join("\n")}`
+    : " []";
   const keyDecisionsYaml = taskRow.key_decisions && taskRow.key_decisions.length > 0
-    ? taskRow.key_decisions.map(d => `  - ${d}`).join("\n")
-    : "  - (none)";
+    ? `\n${taskRow.key_decisions.map(d => `  - ${d}`).join("\n")}`
+    : " []";
 
   // Derive verification_result from evidence if available
   const evidenceList = evidence ?? [];
@@ -230,10 +230,8 @@ export function renderSummaryContent(
 id: ${taskRow.id}
 parent: ${sliceId}
 milestone: ${milestoneId}
-key_files:
-${keyFilesYaml}
-key_decisions:
-${keyDecisionsYaml}
+key_files:${keyFilesYaml}
+key_decisions:${keyDecisionsYaml}
 duration: ${taskRow.duration || ""}
 verification_result: ${verificationResult}
 completed_at: ${taskRow.completed_at || ""}

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

@@ -23,6 +23,7 @@ import { join } from "node:path";
 
 import type { AutoSession } from "./auto/session.js";
 import { debugLog } from "./debug-logger.js";
+import { logWarning } from "./workflow-logger.js";
 import { emitJournalEvent } from "./journal.js";
 import { emitWorktreeCreated, emitWorktreeMerged } from "./worktree-telemetry.js";
 import {
@@ -76,6 +77,13 @@ import {
   teardownAutoWorktree,
 } from "./auto-worktree.js";
 
+const recentWorktreeMergeFailures = new Map<string, number>();
+const MERGE_FAILURE_DEDUPE_MS = 60_000;
+
+export function resetRecentWorktreeMergeFailuresForTest(): void {
+  recentWorktreeMergeFailures.clear();
+}
+
 // ─── Types ───────────────────────────────────────────────────────────────
 
 export interface NotifyCtx {
@@ -525,7 +533,7 @@ export function _enterMilestoneCore(
 
   // Phase B: claim a milestone lease before any worktree mutation. Two
   // workers cannot enter the same milestone concurrently. Best-effort:
-  // skip if no worker registered (single-worker fallback) or DB
+  // warn if no worker registered (single-worker fallback) or skip if DB
   // unavailable; reuse existing lease if we already hold it on this
   // milestone (re-entry within the same session).
   if (s.workerId) {
@@ -618,6 +626,11 @@ export function _enterMilestoneCore(
         });
       }
     }
+  } else {
+    logWarning(
+      "worktree",
+      `enterMilestone(${milestoneId}) ran before auto worker registration; milestone lease was not claimed.`,
+    );
   }
 
   // Resolve the project root for worktree operations via shared helper.
@@ -836,6 +849,32 @@ function rebuildGitService(
   s.gitService = deps.gitServiceFactory(s.basePath);
 }
 
+function emitWorktreeMergeFailedOnce(
+  basePath: string,
+  milestoneId: string,
+  err: unknown,
+): void {
+  const msg = err instanceof Error ? err.message : String(err);
+  const errorCategory = err instanceof Error ? err.name : "Error";
+  const now = Date.now();
+  const key = `${basePath}\0${milestoneId}\0${errorCategory}`;
+  const previous = recentWorktreeMergeFailures.get(key);
+  if (previous && now - previous < MERGE_FAILURE_DEDUPE_MS) return;
+  for (const [candidate, ts] of recentWorktreeMergeFailures) {
+    if (now - ts >= MERGE_FAILURE_DEDUPE_MS) {
+      recentWorktreeMergeFailures.delete(candidate);
+    }
+  }
+  emitJournalEvent(basePath, {
+    ts: new Date().toISOString(),
+    flowId: randomUUID(),
+    seq: 0,
+    eventType: "worktree-merge-failed",
+    data: { milestoneId, error: msg },
+  });
+  recentWorktreeMergeFailures.set(key, now);
+}
+
 // ─── Session-less merge entry (ADR-016 phase 2 / A1) ─────────────────────
 
 /**
@@ -985,13 +1024,7 @@ function _mergeWorktreeModeImpl(
       error: msg,
       fallback: "chdir-to-project-root",
     });
-    emitJournalEvent(originalBasePath || worktreeBasePath, {
-      ts: new Date().toISOString(),
-      flowId: randomUUID(),
-      seq: 0,
-      eventType: "worktree-merge-failed",
-      data: { milestoneId, error: msg },
-    });
+    emitWorktreeMergeFailedOnce(originalBasePath || worktreeBasePath, milestoneId, err);
     // Surface a clear, actionable error. Worktree and milestone branch
     // are intentionally preserved — nothing has been deleted. User can
     // retry /gsd dispatch complete-milestone or merge manually once the
@@ -1702,16 +1735,34 @@ export class WorktreeLifecycle {
   }
 
   /**
-   * Restore `s.basePath` to `s.originalBasePath` and rebuild `s.gitService`.
-   * No-op when `originalBasePath` is empty (fresh sessions).
+   * Restore `s.basePath` to `s.originalBasePath`, chdir process cwd, and
+   * rebuild `s.gitService`. No-op when `originalBasePath` is empty (fresh
+   * sessions).
    *
    * Used by error/cleanup paths that need the session to behave as if the
    * worktree was never entered. Does NOT teardown the worktree directory —
    * callers that need teardown go through `exitMilestone({ merge: false })`.
+   *
+   * ADR-016 phase 3 (#5693): chdir lives inside the verb so callers do not
+   * pair `restoreToProjectRoot()` with a redundant `process.chdir`. The
+   * chdir runs BEFORE the throwable work (`rebuildGitService`, cache
+   * invalidation) so that cleanup-path cwd is restored even if the
+   * downstream rebuild throws. The chdir itself is best-effort; failure is
+   * logged via debugLog and swallowed.
    */
   restoreToProjectRoot(): void {
     if (!this.s.originalBasePath) return;
     this.s.basePath = this.s.originalBasePath;
+    try {
+      process.chdir(this.s.basePath);
+    } catch (err) {
+      debugLog("WorktreeLifecycle", {
+        action: "restoreToProjectRoot",
+        result: "chdir-failed",
+        basePath: this.s.basePath,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
     rebuildGitService(this.s, this.deps);
     invalidateAllCaches();
   }

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

@@ -618,7 +618,7 @@ export function removeWorktree(
       try {
         rmSync(nestedGitPath, { recursive: true, force: true });
         logWarning("reconcile",
-          `Removed nested .git directory from scaffolded project to prevent data loss (#2616)`,
+          `Removed nested .git directory from scaffolded project to prevent data loss`,
           { worktree: name, nestedRepo: nestedDir },
         );
       } catch {