gsd-pi 2.44.0 → 2.45.0-dev.1afbdaa

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

@@ -0,0 +1,127 @@
+/**
+ * validate-milestone handler — the core operation behind gsd_validate_milestone.
+ *
+ * Persists milestone validation results to the assessments table,
+ * renders VALIDATION.md to disk, and invalidates caches.
+ */
+
+import { join } from "node:path";
+
+import {
+  transaction,
+  _getAdapter,
+} from "../gsd-db.js";
+import { resolveMilestonePath, clearPathCache } from "../paths.js";
+import { saveFile, clearParseCache } from "../files.js";
+import { invalidateStateCache } from "../state.js";
+
+export interface ValidateMilestoneParams {
+  milestoneId: string;
+  verdict: "pass" | "needs-attention" | "needs-remediation";
+  remediationRound: number;
+  successCriteriaChecklist: string;
+  sliceDeliveryAudit: string;
+  crossSliceIntegration: string;
+  requirementCoverage: string;
+  verdictRationale: string;
+  remediationPlan?: string;
+}
+
+export interface ValidateMilestoneResult {
+  milestoneId: string;
+  verdict: string;
+  validationPath: string;
+}
+
+function renderValidationMarkdown(params: ValidateMilestoneParams): string {
+  let md = `---
+verdict: ${params.verdict}
+remediation_round: ${params.remediationRound}
+---
+
+# Milestone Validation: ${params.milestoneId}
+
+## Success Criteria Checklist
+${params.successCriteriaChecklist}
+
+## Slice Delivery Audit
+${params.sliceDeliveryAudit}
+
+## Cross-Slice Integration
+${params.crossSliceIntegration}
+
+## Requirement Coverage
+${params.requirementCoverage}
+
+## Verdict Rationale
+${params.verdictRationale}
+`;
+
+  if (params.verdict === "needs-remediation" && params.remediationPlan) {
+    md += `\n## Remediation Plan\n${params.remediationPlan}\n`;
+  }
+
+  return md;
+}
+
+export async function handleValidateMilestone(
+  params: ValidateMilestoneParams,
+  basePath: string,
+): Promise<ValidateMilestoneResult | { error: string }> {
+  if (!params.milestoneId || typeof params.milestoneId !== "string" || params.milestoneId.trim() === "") {
+    return { error: "milestoneId is required and must be a non-empty string" };
+  }
+  const validVerdicts = ["pass", "needs-attention", "needs-remediation"];
+  if (!validVerdicts.includes(params.verdict)) {
+    return { error: `verdict must be one of: ${validVerdicts.join(", ")}` };
+  }
+
+  // ── Filesystem render ──────────────────────────────────────────────────
+  const validationMd = renderValidationMarkdown(params);
+
+  let validationPath: string;
+  const milestoneDir = resolveMilestonePath(basePath, params.milestoneId);
+  if (milestoneDir) {
+    validationPath = join(milestoneDir, `${params.milestoneId}-VALIDATION.md`);
+  } else {
+    const gsdDir = join(basePath, ".gsd");
+    const manualDir = join(gsdDir, "milestones", params.milestoneId);
+    validationPath = join(manualDir, `${params.milestoneId}-VALIDATION.md`);
+  }
+
+  try {
+    await saveFile(validationPath, validationMd);
+  } catch (renderErr) {
+    process.stderr.write(
+      `gsd-db: validate_milestone — disk render failed: ${(renderErr as Error).message}\n`,
+    );
+    return { error: `disk render failed: ${(renderErr as Error).message}` };
+  }
+
+  // ── DB write — store in assessments table ──────────────────────────────
+  const validatedAt = new Date().toISOString();
+
+  transaction(() => {
+    const adapter = _getAdapter()!;
+    adapter.prepare(
+      `INSERT OR REPLACE INTO assessments (path, milestone_id, slice_id, task_id, status, scope, full_content, created_at)
+       VALUES (:path, :mid, NULL, NULL, :verdict, 'milestone-validation', :content, :created_at)`,
+    ).run({
+      ":path": validationPath,
+      ":mid": params.milestoneId,
+      ":verdict": params.verdict,
+      ":content": validationMd,
+      ":created_at": validatedAt,
+    });
+  });
+
+  invalidateStateCache();
+  clearPathCache();
+  clearParseCache();
+
+  return {
+    milestoneId: params.milestoneId,
+    verdict: params.verdict,
+    validationPath,
+  };
+}

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

@@ -520,6 +520,10 @@ export interface CompleteTaskParams {
     verdict: string;
     durationMs: number;
   }>;
+  /** Optional caller-provided identity for audit trail */
+  actorName?: string;
+  /** Optional caller-provided reason this action was triggered */
+  triggerReason?: string;
 }
 
 // ─── Complete Slice Params (gsd_complete_slice tool input) ───────────────
@@ -548,4 +552,8 @@ export interface CompleteSliceParams {
   requires: Array<{ slice: string; provides: string }>;
   affects: string[];
   drillDownPaths: string[];
+  /** Optional caller-provided identity for audit trail */
+  actorName?: string;
+  /** Optional caller-provided reason this action was triggered */
+  triggerReason?: string;
 }

package/src/resources/extensions/gsd/unit-ownership.ts

@@ -0,0 +1,104 @@
+// GSD Extension — Unit Ownership
+// Opt-in per-unit ownership claims for multi-agent safety.
+//
+// An agent can claim a unit (task, slice) before working on it.
+// complete-task and complete-slice enforce ownership when claims exist.
+// If no claim file is present, ownership is not enforced (backward compatible).
+//
+// Claim file location: .gsd/unit-claims.json
+// Unit key format:
+//   task:  "<milestoneId>/<sliceId>/<taskId>"
+//   slice: "<milestoneId>/<sliceId>"
+//
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+import { existsSync, readFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteSync } from "./atomic-write.js";
+
+// ─── Types ───────────────────────────────────────────────────────────────
+
+export interface UnitClaim {
+  agent: string;
+  claimed_at: string;
+}
+
+type ClaimsMap = Record<string, UnitClaim>;
+
+// ─── Key Builders ────────────────────────────────────────────────────────
+
+export function taskUnitKey(milestoneId: string, sliceId: string, taskId: string): string {
+  return `${milestoneId}/${sliceId}/${taskId}`;
+}
+
+export function sliceUnitKey(milestoneId: string, sliceId: string): string {
+  return `${milestoneId}/${sliceId}`;
+}
+
+// ─── File Path ───────────────────────────────────────────────────────────
+
+function claimsPath(basePath: string): string {
+  return join(basePath, ".gsd", "unit-claims.json");
+}
+
+// ─── Read Claims ─────────────────────────────────────────────────────────
+
+function readClaims(basePath: string): ClaimsMap | null {
+  const path = claimsPath(basePath);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as ClaimsMap;
+  } catch {
+    return null;
+  }
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────
+
+/**
+ * Claim a unit for an agent.
+ * Overwrites any existing claim for this unit (last writer wins).
+ */
+export function claimUnit(basePath: string, unitKey: string, agentName: string): void {
+  const claims = readClaims(basePath) ?? {};
+  claims[unitKey] = { agent: agentName, claimed_at: new Date().toISOString() };
+  const dir = join(basePath, ".gsd");
+  mkdirSync(dir, { recursive: true });
+  atomicWriteSync(claimsPath(basePath), JSON.stringify(claims, null, 2) + "\n");
+}
+
+/**
+ * Release a unit claim (remove it from the claims map).
+ */
+export function releaseUnit(basePath: string, unitKey: string): void {
+  const claims = readClaims(basePath);
+  if (!claims || !(unitKey in claims)) return;
+  delete claims[unitKey];
+  atomicWriteSync(claimsPath(basePath), JSON.stringify(claims, null, 2) + "\n");
+}
+
+/**
+ * Get the current owner of a unit, or null if unclaimed / no claims file.
+ */
+export function getOwner(basePath: string, unitKey: string): string | null {
+  const claims = readClaims(basePath);
+  if (!claims) return null;
+  return claims[unitKey]?.agent ?? null;
+}
+
+/**
+ * Check if an actor is authorized to operate on a unit.
+ * Returns null if ownership passes (or is unclaimed / no file).
+ * Returns an error string if a different agent owns the unit.
+ */
+export function checkOwnership(
+  basePath: string,
+  unitKey: string,
+  actorName: string | undefined,
+): string | null {
+  if (!actorName) return null; // no actor identity provided — opt-in, so allow
+  const owner = getOwner(basePath, unitKey);
+  if (owner === null) return null; // unit unclaimed or no claims file
+  if (owner === actorName) return null; // actor is the owner
+  return `Unit ${unitKey} is owned by ${owner}, not ${actorName}`;
+}

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

@@ -0,0 +1,154 @@
+import { createHash, randomUUID } from "node:crypto";
+import { appendFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteSync } from "./atomic-write.js";
+
+// ─── Session ID ───────────────────────────────────────────────────────────
+
+/**
+ * Engine-generated session ID — stable for the lifetime of this process.
+ * Agents can reference this to correlate all events from one run.
+ */
+const ENGINE_SESSION_ID: string = randomUUID();
+
+export function getSessionId(): string {
+  return ENGINE_SESSION_ID;
+}
+
+// ─── Event Types ─────────────────────────────────────────────────────────
+
+export interface WorkflowEvent {
+  cmd: string;           // e.g. "complete_task"
+  params: Record<string, unknown>;
+  ts: string;            // ISO 8601
+  hash: string;          // content hash (hex, 16 chars)
+  actor: "agent" | "system";
+  actor_name?: string;      // e.g. "executor-agent-01" — caller-provided identity
+  trigger_reason?: string;  // e.g. "plan-phase complete" — caller-provided causation
+  session_id: string;       // engine-generated UUID, stable per process lifetime
+}
+
+// ─── appendEvent ─────────────────────────────────────────────────────────
+
+/**
+ * Append one event to .gsd/event-log.jsonl.
+ * Computes a content hash from cmd+params (deterministic, independent of ts/actor/session).
+ * Creates .gsd directory if needed.
+ */
+export function appendEvent(
+  basePath: string,
+  event: Omit<WorkflowEvent, "hash" | "session_id"> & { actor_name?: string; trigger_reason?: string },
+): void {
+  const hash = createHash("sha256")
+    .update(JSON.stringify({ cmd: event.cmd, params: event.params, ts: event.ts }))
+    .digest("hex")
+    .slice(0, 16);
+
+  const fullEvent: WorkflowEvent = {
+    ...event,
+    hash,
+    session_id: ENGINE_SESSION_ID,
+  };
+  const dir = join(basePath, ".gsd");
+  mkdirSync(dir, { recursive: true });
+  appendFileSync(join(dir, "event-log.jsonl"), JSON.stringify(fullEvent) + "\n", "utf-8");
+}
+
+// ─── readEvents ──────────────────────────────────────────────────────────
+
+/**
+ * Read all events from a JSONL file.
+ * Returns empty array if file doesn't exist.
+ * Corrupted lines are skipped with stderr warning.
+ */
+export function readEvents(logPath: string): WorkflowEvent[] {
+  if (!existsSync(logPath)) {
+    return [];
+  }
+
+  const content = readFileSync(logPath, "utf-8");
+  const lines = content.split("\n").filter((l) => l.length > 0);
+  const events: WorkflowEvent[] = [];
+
+  for (const line of lines) {
+    try {
+      events.push(JSON.parse(line) as WorkflowEvent);
+    } catch {
+      process.stderr.write(`workflow-events: skipping corrupted event line: ${line.slice(0, 80)}\n`);
+    }
+  }
+
+  return events;
+}
+
+// ─── findForkPoint ───────────────────────────────────────────────────────
+
+/**
+ * Find the index of the last common event between two logs by comparing hashes.
+ * Returns -1 if the first events differ (completely diverged).
+ * If one log is a prefix of the other, returns length of shorter - 1.
+ */
+export function findForkPoint(
+  logA: WorkflowEvent[],
+  logB: WorkflowEvent[],
+): number {
+  const minLen = Math.min(logA.length, logB.length);
+  let lastCommon = -1;
+
+  for (let i = 0; i < minLen; i++) {
+    if (logA[i]!.hash === logB[i]!.hash) {
+      lastCommon = i;
+    } else {
+      break;
+    }
+  }
+
+  return lastCommon;
+}
+
+// ─── compactMilestoneEvents ─────────────────────────────────────────────────
+
+/**
+ * Archive a milestone's events from the active log to a separate file.
+ * Active log retains only events from other milestones.
+ * Archived file is kept on disk for forensics.
+ *
+ * @param basePath - Project root (parent of .gsd/)
+ * @param milestoneId - The milestone whose events should be archived
+ * @returns { archived: number } — count of events moved to archive
+ */
+export function compactMilestoneEvents(
+  basePath: string,
+  milestoneId: string,
+): { archived: number } {
+  const logPath = join(basePath, ".gsd", "event-log.jsonl");
+  const archivePath = join(basePath, ".gsd", `event-log-${milestoneId}.jsonl.archived`);
+
+  const allEvents = readEvents(logPath);
+  const toArchive = allEvents.filter(
+    (e) => (e.params as { milestoneId?: string }).milestoneId === milestoneId,
+  );
+  const remaining = allEvents.filter(
+    (e) => (e.params as { milestoneId?: string }).milestoneId !== milestoneId,
+  );
+
+  if (toArchive.length === 0) {
+    return { archived: 0 };
+  }
+
+  // Write archived events to .jsonl.archived file (crash-safe)
+  atomicWriteSync(
+    archivePath,
+    toArchive.map((e) => JSON.stringify(e)).join("\n") + "\n",
+  );
+
+  // Truncate active log to remaining events only
+  atomicWriteSync(
+    logPath,
+    remaining.length > 0
+      ? remaining.map((e) => JSON.stringify(e)).join("\n") + "\n"
+      : "",
+  );
+
+  return { archived: toArchive.length };
+}

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

@@ -0,0 +1,243 @@
+// GSD Extension — Workflow Logger
+// Centralized warning/error accumulator for the workflow engine pipeline.
+// Captures structured entries that the auto-loop can drain after each unit
+// to surface root causes for stuck loops, silent degradation, and blocked writes.
+// All entries are also persisted to .gsd/audit-log.jsonl for post-mortem analysis.
+//
+// Stderr policy: every logWarning/logError call writes immediately to stderr
+// for terminal visibility. This is intentional — unlike debug-logger (which is
+// opt-in and zero-overhead when disabled), workflow-logger covers operational
+// warnings/errors that should always be visible. There is no disable flag.
+//
+// Singleton safety: _buffer is module-level and shared across all calls within
+// a process. The auto-loop must call _resetLogs() (or drainAndSummarize()) at
+// the start of each unit to prevent log bleed between units running in the same
+// Node process.
+
+import { appendFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+// ─── Types ──────────────────────────────────────────────────────────────
+
+export type LogSeverity = "warn" | "error";
+
+export type LogComponent =
+  | "engine"        // WorkflowEngine afterCommand side effects
+  | "projection"    // Projection rendering
+  | "manifest"      // Manifest write
+  | "event-log"     // Event append
+  | "intercept"     // Write intercept / tool-call blocks
+  | "migration"     // Auto-migration from markdown
+  | "state"         // deriveState fallback/degradation
+  | "tool"          // Tool handler errors
+  | "compaction"    // Event compaction
+  | "reconcile";    // Worktree reconciliation
+
+export interface LogEntry {
+  ts: string;
+  severity: LogSeverity;
+  component: LogComponent;
+  message: string;
+  /** Optional structured context (file path, command name, etc.) */
+  context?: Record<string, string>;
+}
+
+// ─── Buffer & Persistent Audit ──────────────────────────────────────────
+
+const MAX_BUFFER = 100;
+let _buffer: LogEntry[] = [];
+let _auditBasePath: string | null = null;
+
+/**
+ * Set the base path for persistent audit log writes.
+ * Should be called once at engine init with the project root.
+ * Until set, log entries are buffered in-memory only.
+ */
+export function setLogBasePath(basePath: string): void {
+  _auditBasePath = basePath;
+}
+
+// ─── Public API ─────────────────────────────────────────────────────────
+
+/**
+ * Record a warning. Also writes to stderr for terminal visibility.
+ */
+export function logWarning(
+  component: LogComponent,
+  message: string,
+  context?: Record<string, string>,
+): void {
+  _push("warn", component, message, context);
+}
+
+/**
+ * Record an error. Also writes to stderr for terminal visibility.
+ */
+export function logError(
+  component: LogComponent,
+  message: string,
+  context?: Record<string, string>,
+): void {
+  _push("error", component, message, context);
+}
+
+/**
+ * Drain all accumulated entries and clear the buffer.
+ * Returns entries oldest-first.
+ *
+ * WARNING: Call summarizeLogs() or drainAndSummarize() BEFORE calling this
+ * if you need a summary — drainLogs() clears the buffer immediately.
+ */
+export function drainLogs(): LogEntry[] {
+  const entries = _buffer;
+  _buffer = [];
+  return entries;
+}
+
+/**
+ * Atomically summarize then drain — the safe way to consume logs.
+ * Use this in the auto-loop instead of calling summarizeLogs() + drainLogs()
+ * separately to avoid the ordering footgun.
+ */
+export function drainAndSummarize(): { logs: LogEntry[]; summary: string | null } {
+  const summary = summarizeLogs();
+  const logs = drainLogs();
+  return { logs, summary };
+}
+
+/**
+ * Peek at current entries without clearing.
+ */
+export function peekLogs(): readonly LogEntry[] {
+  return _buffer;
+}
+
+/**
+ * Returns true if the buffer contains any error-severity entries.
+ */
+export function hasErrors(): boolean {
+  return _buffer.some((e) => e.severity === "error");
+}
+
+/**
+ * Returns true if the buffer contains any warn-severity entries.
+ * Use hasAnyIssues() if you want to check for either severity.
+ */
+export function hasWarnings(): boolean {
+  return _buffer.some((e) => e.severity === "warn");
+}
+
+/**
+ * Returns true if the buffer contains any entries (warn or error).
+ */
+export function hasAnyIssues(): boolean {
+  return _buffer.length > 0;
+}
+
+/**
+ * Get a one-line summary of accumulated issues for stuck detection messages.
+ * Returns null if no entries.
+ *
+ * Must be called BEFORE drainLogs() — use drainAndSummarize() for safe ordering.
+ */
+export function summarizeLogs(): string | null {
+  if (_buffer.length === 0) return null;
+  const errors = _buffer.filter((e) => e.severity === "error");
+  const warns = _buffer.filter((e) => e.severity === "warn");
+
+  const parts: string[] = [];
+  if (errors.length > 0) {
+    parts.push(`${errors.length} error(s): ${errors.map((e) => e.message).join("; ")}`);
+  }
+  if (warns.length > 0) {
+    parts.push(`${warns.length} warning(s): ${warns.map((e) => e.message).join("; ")}`);
+  }
+  return parts.join(" | ");
+}
+
+/**
+ * Format entries for display (used by auto-loop post-unit notification).
+ * Note: context fields are not included in the formatted output.
+ */
+export function formatForNotification(entries: readonly LogEntry[]): string {
+  if (entries.length === 0) return "";
+  if (entries.length === 1) {
+    const e = entries[0];
+    return `[${e.component}] ${e.message}`;
+  }
+  return entries
+    .map((e) => `[${e.component}] ${e.message}`)
+    .join("\n");
+}
+
+/**
+ * Read all entries from the persistent audit log.
+ * Returns empty array if no basePath is set or the file doesn't exist.
+ */
+export function readAuditLog(basePath?: string): LogEntry[] {
+  const bp = basePath ?? _auditBasePath;
+  if (!bp) return [];
+  const auditPath = join(bp, ".gsd", "audit-log.jsonl");
+  if (!existsSync(auditPath)) return [];
+  try {
+    const content = readFileSync(auditPath, "utf-8");
+    return content
+      .split("\n")
+      .filter((l) => l.length > 0)
+      .map((l) => {
+        try { return JSON.parse(l) as LogEntry; } catch { return null; }
+      })
+      .filter((e): e is LogEntry => e !== null);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Reset buffer. Call at the start of each auto-loop unit to prevent log bleed
+ * between units running in the same process. Also used in tests via _resetLogs().
+ */
+export function _resetLogs(): void {
+  _buffer = [];
+  _auditBasePath = null;
+}
+
+// ─── Internal ───────────────────────────────────────────────────────────
+
+function _push(
+  severity: LogSeverity,
+  component: LogComponent,
+  message: string,
+  context?: Record<string, string>,
+): void {
+  const entry: LogEntry = {
+    ts: new Date().toISOString(),
+    severity,
+    component,
+    message,
+    ...(context ? { context } : {}),
+  };
+
+  // Always forward to stderr so terminal watchers see it (see module header for policy)
+  const prefix = severity === "error" ? "ERROR" : "WARN";
+  const ctxStr = context ? ` ${JSON.stringify(context)}` : "";
+  process.stderr.write(`[gsd:${component}] ${prefix}: ${message}${ctxStr}\n`);
+
+  // Buffer for auto-loop to drain
+  _buffer.push(entry);
+  if (_buffer.length > MAX_BUFFER) {
+    _buffer.shift();
+  }
+
+  // Persist to .gsd/audit-log.jsonl so entries survive context resets
+  if (_auditBasePath) {
+    try {
+      const auditDir = join(_auditBasePath, ".gsd");
+      mkdirSync(auditDir, { recursive: true });
+      appendFileSync(join(auditDir, "audit-log.jsonl"), JSON.stringify(entry) + "\n", "utf-8");
+    } catch (auditErr) {
+      // Best-effort — never let audit write failures bubble up
+      process.stderr.write(`[gsd:audit] failed to persist log entry: ${(auditErr as Error).message}\n`);
+    }
+  }
+}