gsd-pi 2.82.0 → 3.0.0

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

@@ -1,6 +1,6 @@
 import { clearParseCache } from "../files.js";
 import { isClosedStatus } from "../status-guards.js";
-import { isNonEmptyString, validateStringArray } from "../validation.js";
+import { isNonEmptyString, validateStringArray, validateTitle } from "../validation.js";
 import {
   transaction,
   getMilestone,
@@ -148,6 +148,8 @@ function validateSlices(value: unknown): PlanMilestoneSliceInput[] {
     if (seen.has(sliceId)) throw new Error(`slices[${index}].sliceId must be unique`);
     seen.add(sliceId);
     if (!isNonEmptyString(title)) throw new Error(`slices[${index}].title must be a non-empty string`);
+    const titleIssue = validateTitle(title);
+    if (titleIssue) throw new Error(`slices[${index}].title is invalid: ${titleIssue}`);
     if (!isNonEmptyString(risk)) throw new Error(`slices[${index}].risk must be a non-empty string`);
     if (!Array.isArray(depends) || depends.some((item) => !isNonEmptyString(item))) {
       throw new Error(`slices[${index}].depends must be an array of non-empty strings`);
@@ -190,6 +192,8 @@ function validateParams(params: PlanMilestoneParams): PlanMilestoneParams {
   if (!isNonEmptyString(params?.milestoneId)) throw new Error("milestoneId is required");
   if (!isNonEmptyString(params?.title)) throw new Error("title is required");
   if (!isNonEmptyString(params?.vision)) throw new Error("vision is required");
+  const milestoneTitleIssue = validateTitle(params.title);
+  if (milestoneTitleIssue) throw new Error(`title is invalid: ${milestoneTitleIssue}`);
 
   return {
     ...params,

package/src/resources/extensions/gsd/tools/plan-slice.ts

@@ -1,3 +1,5 @@
+import { existsSync, rmSync } from "node:fs";
+import { join, relative } from "node:path";
 import { clearParseCache } from "../files.js";
 import { isClosedStatus, isDeferredStatus } from "../status-guards.js";
 import { isNonEmptyString, validateStringArray } from "../validation.js";
@@ -5,11 +7,15 @@ import {
   transaction,
   getMilestone,
   getSlice,
+  getSliceTasks,
   insertTask,
   upsertSlicePlanning,
   upsertTaskPlanning,
   insertGateRow,
   updateSliceStatus,
+  setSliceSketchFlag,
+  deleteTask,
+  deleteArtifactByPath,
 } from "../gsd-db.js";
 import type { GateId } from "../types.js";
 import { invalidateStateCache } from "../state.js";
@@ -19,6 +25,9 @@ import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
 import { validatePlanningPathScope } from "../planning-path-scope.js";
+import { checkFilePathConsistency, checkTaskOrdering } from "../pre-execution-checks.js";
+import type { TaskRow } from "../db-task-slice-rows.js";
+import { buildTaskFileName, gsdProjectionRoot } from "../paths.js";
 
 export interface PlanSliceTaskInput {
   taskId: string;
@@ -86,16 +95,10 @@ function validateTasks(value: unknown): PlanSliceTaskInput[] {
     if (!isNonEmptyString(title)) throw new Error(`tasks[${index}].title must be a non-empty string`);
     if (!isNonEmptyString(description)) throw new Error(`tasks[${index}].description must be a non-empty string`);
     if (!isNonEmptyString(estimate)) throw new Error(`tasks[${index}].estimate must be a non-empty string`);
-    if (!Array.isArray(files) || files.some((item) => !isNonEmptyString(item))) {
-      throw new Error(`tasks[${index}].files must be an array of non-empty strings`);
-    }
+    const validatedFiles = validateStringArray(files, `tasks[${index}].files`);
     if (!isNonEmptyString(verify)) throw new Error(`tasks[${index}].verify must be a non-empty string`);
-    if (!Array.isArray(inputs) || inputs.some((item) => !isNonEmptyString(item))) {
-      throw new Error(`tasks[${index}].inputs must be an array of non-empty strings`);
-    }
-    if (!Array.isArray(expectedOutput) || expectedOutput.some((item) => !isNonEmptyString(item))) {
-      throw new Error(`tasks[${index}].expectedOutput must be an array of non-empty strings`);
-    }
+    const validatedInputs = validateStringArray(inputs, `tasks[${index}].inputs`);
+    const validatedExpectedOutput = validateStringArray(expectedOutput, `tasks[${index}].expectedOutput`);
     if (observabilityImpact !== undefined && !isNonEmptyString(observabilityImpact)) {
       throw new Error(`tasks[${index}].observabilityImpact must be a non-empty string when provided`);
     }
@@ -105,10 +108,10 @@ function validateTasks(value: unknown): PlanSliceTaskInput[] {
       title,
       description,
       estimate,
-      files,
+      files: validatedFiles,
       verify,
-      inputs,
-      expectedOutput,
+      inputs: validatedInputs,
+      expectedOutput: validatedExpectedOutput,
       observabilityImpact: typeof observabilityImpact === "string" ? observabilityImpact : "",
     };
   });
@@ -131,6 +134,56 @@ function validateParams(params: PlanSliceParams): PlanSliceParams {
   };
 }
 
+function toTaskRows(params: PlanSliceParams): TaskRow[] {
+  return params.tasks.map((task, index) => ({
+    milestone_id: params.milestoneId,
+    slice_id: params.sliceId,
+    id: task.taskId,
+    title: task.title,
+    status: "pending",
+    one_liner: "",
+    narrative: "",
+    verification_result: "",
+    duration: "",
+    completed_at: null,
+    blocker_discovered: false,
+    deviations: "",
+    known_issues: "",
+    key_files: [],
+    key_decisions: [],
+    full_summary_md: "",
+    description: task.description,
+    estimate: task.estimate,
+    files: task.files,
+    verify: task.verify,
+    inputs: task.inputs,
+    expected_output: task.expectedOutput,
+    observability_impact: task.observabilityImpact ?? "",
+    full_plan_md: task.fullPlanMd ?? "",
+    sequence: index + 1,
+    blocker_source: "",
+    escalation_pending: 0,
+    escalation_awaiting_review: 0,
+    escalation_artifact_path: null,
+    escalation_override_applied_at: null,
+  }));
+}
+
+function validateTaskPathsBeforePersist(params: PlanSliceParams, basePath: string): string | null {
+  const taskRows = toTaskRows(params);
+  const checks = [
+    ...checkFilePathConsistency(taskRows, basePath),
+    ...checkTaskOrdering(taskRows, basePath),
+  ];
+  const blocking = checks.filter((check) => !check.passed && check.blocking);
+
+  if (blocking.length === 0) return null;
+
+  return blocking
+    .map((check) => `[${check.category}] ${check.target}: ${check.message}`)
+    .join("\n");
+}
+
 export async function handlePlanSlice(
   rawParams: PlanSliceParams,
   basePath: string,
@@ -154,10 +207,16 @@ export async function handlePlanSlice(
     return { error: `validation failed: ${pathScopeError}` };
   }
 
+  const pathError = validateTaskPathsBeforePersist(params, basePath);
+  if (pathError) {
+    return { error: `pre-execution validation failed:\n${pathError}` };
+  }
+
   // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
   // Guards must be inside the transaction so the state they check cannot
   // change between the read and the write (#2723).
   let guardError: string | null = null;
+  let omittedTaskIds: string[] = [];
 
   try {
     transaction(() => {
@@ -181,9 +240,23 @@ export async function handlePlanSlice(
         return;
       }
 
+      const newTaskIds = new Set(params.tasks.map((task) => task.taskId));
+      const existingTasks = getSliceTasks(params.milestoneId, params.sliceId);
+      omittedTaskIds = existingTasks
+        .filter((task) => !newTaskIds.has(task.id))
+        .map((task) => task.id);
+
+      for (const task of existingTasks) {
+        if (!newTaskIds.has(task.id) && isClosedStatus(task.status)) {
+          guardError = `cannot remove completed task ${task.id}`;
+          return;
+        }
+      }
+
       if (isDeferredStatus(parentSlice.status)) {
         updateSliceStatus(params.milestoneId, params.sliceId, "pending");
       }
+      setSliceSketchFlag(params.milestoneId, params.sliceId, false);
 
       upsertSlicePlanning(params.milestoneId, params.sliceId, {
         goal: params.goal,
@@ -193,6 +266,10 @@ export async function handlePlanSlice(
         observabilityImpact: params.observabilityImpact,
       });
 
+      for (const taskId of omittedTaskIds) {
+        deleteTask(params.milestoneId, params.sliceId, taskId);
+      }
+
       for (const task of params.tasks) {
         insertTask({
           id: task.taskId,
@@ -237,6 +314,14 @@ export async function handlePlanSlice(
   }
 
   try {
+    const tasksDir = join(gsdProjectionRoot(basePath), "milestones", params.milestoneId, "slices", params.sliceId, "tasks");
+    for (const taskId of omittedTaskIds) {
+      const taskPlanPath = join(tasksDir, buildTaskFileName(taskId, "PLAN"));
+      if (existsSync(taskPlanPath)) rmSync(taskPlanPath, { force: true });
+      const artifactPath = relative(gsdProjectionRoot(basePath), taskPlanPath).replace(/\\/g, "/");
+      deleteArtifactByPath(artifactPath);
+    }
+
     const renderResult = await renderPlanFromDb(basePath, params.milestoneId, params.sliceId);
     invalidateStateCache();
     clearParseCache();

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(),

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" | "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-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;
 }