gsd-pi 2.63.0 → 2.64.0-dev.6fe1e44

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

@@ -0,0 +1,108 @@
+/**
+ * Post-unit file change validator for auto-mode safety harness.
+ * Compares actual git diff against the task plan's expected output files.
+ *
+ * Uses tasks.expected_output (DB column, populated from per-task ## Expected Output)
+ * and tasks.files (from slice PLAN.md - Files: subline) as the expected set.
+ * Compares against git diff HEAD~1 --name-only after auto-commit.
+ *
+ * Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+ */
+
+import { execFileSync } from "node:child_process";
+import { logWarning } from "../workflow-logger.js";
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface FileViolation {
+  severity: "info" | "warning";
+  file: string;
+  reason: string;
+}
+
+export interface FileChangeAudit {
+  expectedFiles: string[];
+  actualFiles: string[];
+  unexpectedFiles: string[];
+  missingFiles: string[];
+  violations: FileViolation[];
+}
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Validate file changes after auto-commit for an execute-task unit.
+ * Returns null if task data is unavailable or DB is not loaded.
+ *
+ * @param basePath - Working directory (worktree or project root)
+ * @param expectedOutput - JSON array from tasks.expected_output DB column
+ * @param plannedFiles - JSON array from tasks.files DB column
+ */
+export function validateFileChanges(
+  basePath: string,
+  expectedOutput: string[],
+  plannedFiles: string[],
+): FileChangeAudit | null {
+  const allExpected = new Set([...expectedOutput, ...plannedFiles]);
+
+  // If no expected files were planned, skip validation
+  if (allExpected.size === 0) return null;
+
+  // Get actual changed files from last commit
+  const actualFiles = getChangedFilesFromLastCommit(basePath);
+  if (!actualFiles) return null;
+
+  // Filter out .gsd/ internal files — only validate project source files
+  const projectFiles = actualFiles.filter(f => !f.startsWith(".gsd/") && !f.startsWith(".gsd\\"));
+
+  // Normalize expected paths (strip leading ./ or /)
+  const normalizedExpected = new Set(
+    [...allExpected].map(f => f.replace(/^\.\//, "").replace(/^\//, "")),
+  );
+
+  // Compute symmetric difference
+  const unexpectedFiles = projectFiles.filter(f => !normalizedExpected.has(f));
+  const missingFiles = [...normalizedExpected].filter(f => !projectFiles.includes(f));
+
+  const violations: FileViolation[] = [];
+
+  for (const f of unexpectedFiles) {
+    violations.push({
+      severity: "warning",
+      file: f,
+      reason: "Modified but not in task plan's expected output",
+    });
+  }
+
+  for (const f of missingFiles) {
+    violations.push({
+      severity: "info",
+      file: f,
+      reason: "Listed in task plan but not modified",
+    });
+  }
+
+  return {
+    expectedFiles: [...normalizedExpected],
+    actualFiles: projectFiles,
+    unexpectedFiles,
+    missingFiles,
+    violations,
+  };
+}
+
+// ─── Internals ──────────────────────────────────────────────────────────────
+
+function getChangedFilesFromLastCommit(basePath: string): string[] | null {
+  try {
+    const result = execFileSync(
+      "git",
+      ["diff", "--name-only", "HEAD~1", "HEAD"],
+      { cwd: basePath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" },
+    ).trim();
+    return result ? result.split("\n").filter(Boolean) : [];
+  } catch (e) {
+    logWarning("safety", `git diff failed in file-change-validator: ${(e as Error).message}`);
+    return null;
+  }
+}

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

@@ -0,0 +1,106 @@
+/**
+ * Pre-unit git checkpoint and rollback for auto-mode safety harness.
+ * Uses the existing refs/gsd/ namespace (already pruned by doctor).
+ *
+ * Creates a lightweight ref at HEAD before unit execution. On failure,
+ * the ref can be used to rollback the branch to the pre-unit state.
+ *
+ * Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+ */
+
+import { execFileSync } from "node:child_process";
+import { logWarning } from "../workflow-logger.js";
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+const CHECKPOINT_PREFIX = "refs/gsd/checkpoints/";
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Create a checkpoint ref at the current HEAD for the given unit.
+ * Returns the SHA of HEAD, or null if the operation fails.
+ */
+export function createCheckpoint(basePath: string, unitId: string): string | null {
+  try {
+    const sha = execFileSync("git", ["rev-parse", "HEAD"], {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+    }).trim();
+
+    if (!sha || sha.length < 7) return null;
+
+    // Sanitize unitId for use in ref path (replace / with -)
+    const safeUnitId = unitId.replace(/\//g, "-");
+
+    execFileSync("git", ["update-ref", `${CHECKPOINT_PREFIX}${safeUnitId}`, sha], {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    return sha;
+  } catch (e) {
+    logWarning("safety", `checkpoint creation failed: ${(e as Error).message}`);
+    return null;
+  }
+}
+
+/**
+ * Rollback the current branch to a checkpoint SHA.
+ * Returns true on success, false on failure.
+ *
+ * WARNING: This is a destructive operation — it discards all changes
+ * since the checkpoint. Only call when the user has opted in via
+ * safety_harness.auto_rollback or an explicit manual trigger.
+ */
+export function rollbackToCheckpoint(
+  basePath: string,
+  unitId: string,
+  sha: string,
+): boolean {
+  try {
+    // Get current branch name
+    const branch = execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+    }).trim();
+
+    if (!branch || branch === "HEAD") {
+      logWarning("safety", "rollback: detached HEAD state, cannot rollback");
+      return false;
+    }
+
+    // Reset branch pointer and working tree to checkpoint SHA in one step.
+    // Using `git reset --hard <sha>` works on the currently checked-out branch
+    // (unlike `git branch -f` which is rejected for checked-out branches).
+    execFileSync("git", ["reset", "--hard", sha], {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    // Cleanup checkpoint ref
+    cleanupCheckpoint(basePath, unitId);
+
+    return true;
+  } catch (e) {
+    logWarning("safety", `rollback failed: ${(e as Error).message}`);
+    return false;
+  }
+}
+
+/**
+ * Remove a checkpoint ref after successful unit completion.
+ */
+export function cleanupCheckpoint(basePath: string, unitId: string): void {
+  try {
+    const safeUnitId = unitId.replace(/\//g, "-");
+    execFileSync("git", ["update-ref", "-d", `${CHECKPOINT_PREFIX}${safeUnitId}`], {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+  } catch {
+    // Non-fatal — ref may already have been cleaned up
+  }
+}

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

@@ -0,0 +1,105 @@
+/**
+ * Safety Harness — central module for LLM damage control during auto-mode.
+ * Provides types, preference resolution, and orchestration for all safety components.
+ *
+ * Components:
+ * - evidence-collector.ts: Real-time tool call tracking
+ * - destructive-guard.ts: Bash command classification
+ * - file-change-validator.ts: Post-unit git diff vs plan
+ * - evidence-cross-ref.ts: Claimed vs actual verification evidence
+ * - git-checkpoint.ts: Pre-unit checkpoints + rollback
+ * - content-validator.ts: Output quality validation
+ *
+ * Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+ */
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface SafetyHarnessConfig {
+  enabled: boolean;
+  evidence_collection: boolean;
+  file_change_validation: boolean;
+  evidence_cross_reference: boolean;
+  destructive_command_warnings: boolean;
+  content_validation: boolean;
+  checkpoints: boolean;
+  auto_rollback: boolean;
+  timeout_scale_cap: number;
+}
+
+// ─── Defaults ───────────────────────────────────────────────────────────────
+
+const DEFAULTS: SafetyHarnessConfig = {
+  enabled: true,
+  evidence_collection: true,
+  file_change_validation: true,
+  evidence_cross_reference: true,
+  destructive_command_warnings: true,
+  content_validation: true,
+  checkpoints: true,
+  auto_rollback: false,
+  timeout_scale_cap: 6,
+};
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Resolve safety harness configuration from raw preferences.
+ * Missing fields fall back to defaults.
+ */
+export function resolveSafetyHarnessConfig(
+  raw: Record<string, unknown> | undefined,
+): SafetyHarnessConfig {
+  if (!raw) return { ...DEFAULTS };
+
+  return {
+    enabled: typeof raw.enabled === "boolean" ? raw.enabled : DEFAULTS.enabled,
+    evidence_collection: typeof raw.evidence_collection === "boolean" ? raw.evidence_collection : DEFAULTS.evidence_collection,
+    file_change_validation: typeof raw.file_change_validation === "boolean" ? raw.file_change_validation : DEFAULTS.file_change_validation,
+    evidence_cross_reference: typeof raw.evidence_cross_reference === "boolean" ? raw.evidence_cross_reference : DEFAULTS.evidence_cross_reference,
+    destructive_command_warnings: typeof raw.destructive_command_warnings === "boolean" ? raw.destructive_command_warnings : DEFAULTS.destructive_command_warnings,
+    content_validation: typeof raw.content_validation === "boolean" ? raw.content_validation : DEFAULTS.content_validation,
+    checkpoints: typeof raw.checkpoints === "boolean" ? raw.checkpoints : DEFAULTS.checkpoints,
+    auto_rollback: typeof raw.auto_rollback === "boolean" ? raw.auto_rollback : DEFAULTS.auto_rollback,
+    timeout_scale_cap: typeof raw.timeout_scale_cap === "number" ? raw.timeout_scale_cap : DEFAULTS.timeout_scale_cap,
+  };
+}
+
+/**
+ * Check if the safety harness is enabled.
+ * Used as a fast gate at hook registration and phase integration points.
+ */
+export function isHarnessEnabled(
+  raw: Record<string, unknown> | undefined,
+): boolean {
+  if (!raw) return DEFAULTS.enabled;
+  if (typeof raw.enabled === "boolean") return raw.enabled;
+  return DEFAULTS.enabled;
+}
+
+// ─── Re-exports ─────────────────────────────────────────────────────────────
+
+export {
+  resetEvidence,
+  getEvidence,
+  getBashEvidence,
+  getFilePaths,
+  recordToolCall,
+  recordToolResult,
+} from "./evidence-collector.js";
+
+export type { EvidenceEntry, BashEvidence, FileWriteEvidence, FileEditEvidence } from "./evidence-collector.js";
+
+export { classifyCommand } from "./destructive-guard.js";
+export type { CommandClassification } from "./destructive-guard.js";
+
+export { validateFileChanges } from "./file-change-validator.js";
+export type { FileChangeAudit, FileViolation } from "./file-change-validator.js";
+
+export { crossReferenceEvidence } from "./evidence-cross-ref.js";
+export type { ClaimedEvidence, EvidenceMismatch } from "./evidence-cross-ref.js";
+
+export { createCheckpoint, rollbackToCheckpoint, cleanupCheckpoint } from "./git-checkpoint.js";
+
+export { validateContent } from "./content-validator.js";
+export type { ContentViolation } from "./content-validator.js";

package/src/resources/extensions/gsd/slice-parallel-conflict.ts

@@ -0,0 +1,86 @@
+/**
+ * GSD Slice Parallel Conflict Detection — File overlap analysis between slices.
+ *
+ * Reads PLAN.md for each slice and extracts file paths mentioned in task
+ * descriptions. If two slices share more than 5 file paths, they are considered
+ * conflicting and should not run in parallel.
+ *
+ * Conservative by default: missing PLAN = block parallel execution.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+// ─── File Path Extraction ─────────────────────────────────────────────────────
+
+/**
+ * Extract file paths from a PLAN.md content string.
+ * Matches common patterns like `src/...`, `lib/...`, paths with extensions.
+ */
+function extractFilePaths(content: string): Set<string> {
+  const paths = new Set<string>();
+
+  // Match file-like patterns: word/word paths with extensions, or src/lib/etc prefixed paths
+  const patterns = [
+    // Paths like src/foo/bar.ts, lib/utils.js, etc.
+    /(?:src|lib|test|tests|app|pkg|cmd|internal|components|pages|api|utils|config|scripts|dist|build)\/[\w./-]+\.\w+/g,
+    // Generic path with at least one slash and extension
+    /(?<!\w)[\w-]+\/[\w./-]+\.\w{1,5}(?!\w)/g,
+  ];
+
+  for (const pattern of patterns) {
+    const matches = content.matchAll(pattern);
+    for (const match of matches) {
+      paths.add(match[0]);
+    }
+  }
+
+  return paths;
+}
+
+// ─── Conflict Detection ──────────────────────────────────────────────────────
+
+/**
+ * Check if two slices have file conflicts that would block parallel execution.
+ *
+ * @param basePath  Project root path.
+ * @param mid       Milestone ID.
+ * @param sliceA    First slice ID.
+ * @param sliceB    Second slice ID.
+ * @returns         true if parallel is unsafe (>5 shared files or missing plan).
+ */
+export function hasFileConflict(
+  basePath: string,
+  mid: string,
+  sliceA: string,
+  sliceB: string,
+): boolean {
+  const planPathA = join(basePath, ".gsd", "milestones", mid, sliceA, "PLAN.md");
+  const planPathB = join(basePath, ".gsd", "milestones", mid, sliceB, "PLAN.md");
+
+  // Conservative: missing PLAN = block
+  if (!existsSync(planPathA) || !existsSync(planPathB)) {
+    return true;
+  }
+
+  const contentA = readFileSync(planPathA, "utf-8");
+  const contentB = readFileSync(planPathB, "utf-8");
+
+  const filesA = extractFilePaths(contentA);
+  const filesB = extractFilePaths(contentB);
+
+  // If either has no files extracted, no conflict detectable → allow
+  if (filesA.size === 0 || filesB.size === 0) {
+    return false;
+  }
+
+  // Count shared files
+  let sharedCount = 0;
+  for (const file of filesA) {
+    if (filesB.has(file)) {
+      sharedCount++;
+    }
+  }
+
+  return sharedCount > 5;
+}

package/src/resources/extensions/gsd/slice-parallel-eligibility.ts

@@ -0,0 +1,73 @@
+/**
+ * GSD Slice Parallel Eligibility — Pure function to determine which slices
+ * within a milestone can run in parallel based on dependency satisfaction.
+ *
+ * This is the slice-level equivalent of parallel-eligibility.ts (which operates
+ * at milestone scope). The key difference is the positional fallback: slices
+ * without explicit dependencies use sequential ordering as an implicit constraint.
+ */
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface SliceInput {
+  id: string;
+  done: boolean;
+  depends: string[];
+}
+
+export interface EligibleSlice {
+  id: string;
+}
+
+// ─── Core Logic ───────────────────────────────────────────────────────────────
+
+/**
+ * Determine which slices are eligible for parallel execution.
+ *
+ * Rules:
+ * 1. Done slices are never eligible (nothing to do).
+ * 2. A slice with explicit `depends` entries is eligible when ALL deps
+ *    appear in `completedSliceIds`.
+ * 3. A slice with NO `depends` entries uses positional fallback: it is
+ *    eligible only when every positionally-earlier slice is done.
+ *    This preserves backward compatibility with roadmaps that don't
+ *    declare inter-slice dependencies.
+ *
+ * @param slices      All slices in the milestone (ordered by position).
+ * @param completedSliceIds  Set of slice IDs that are already complete.
+ * @returns           Array of eligible slice descriptors.
+ */
+export function getEligibleSlices(
+  slices: SliceInput[],
+  completedSliceIds: Set<string>,
+): EligibleSlice[] {
+  const eligible: EligibleSlice[] = [];
+
+  for (let i = 0; i < slices.length; i++) {
+    const slice = slices[i];
+
+    // Rule 1: skip done slices
+    if (slice.done) continue;
+
+    const hasExplicitDeps = slice.depends.length > 0;
+
+    if (hasExplicitDeps) {
+      // Rule 2: explicit dependencies — all must be satisfied
+      const allDepsSatisfied = slice.depends.every(dep => completedSliceIds.has(dep));
+      if (allDepsSatisfied) {
+        eligible.push({ id: slice.id });
+      }
+    } else {
+      // Rule 3: no deps declared — positional fallback
+      // Eligible only if all positionally-earlier slices are done
+      const allEarlierDone = slices.slice(0, i).every(
+        earlier => earlier.done || completedSliceIds.has(earlier.id),
+      );
+      if (allEarlierDone) {
+        eligible.push({ id: slice.id });
+      }
+    }
+  }
+
+  return eligible;
+}