gsd-pi 2.44.0-dev.d25d507 → 2.45.0-dev.1afbdaa

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

@@ -11,6 +11,9 @@ import {
 } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
 import { renderPlanFromDb, renderReplanFromDb } from "../markdown-renderer.js";
+import { renderAllProjections } from "../workflow-projections.js";
+import { writeManifest } from "../workflow-manifest.js";
+import { appendEvent } from "../workflow-events.js";
 
 export interface ReplanSliceTaskInput {
   taskId: string;
@@ -21,6 +24,7 @@ export interface ReplanSliceTaskInput {
   verify: string;
   inputs: string[];
   expectedOutput: string[];
+  fullPlanMd?: string;
 }
 
 export interface ReplanSliceParams {
@@ -31,6 +35,10 @@ export interface ReplanSliceParams {
   whatChanged: string;
   updatedTasks: ReplanSliceTaskInput[];
   removedTaskIds: string[];
+  /** Optional caller-provided identity for audit trail */
+  actorName?: string;
+  /** Optional caller-provided reason this action was triggered */
+  triggerReason?: string;
 }
 
 export interface ReplanSliceResult {
@@ -82,11 +90,23 @@ export async function handleReplanSlice(
     return { error: `validation failed: ${(err as Error).message}` };
   }
 
-  // ── Verify parent slice exists ────────────────────────────────────
+  // ── Verify parent slice exists and is not closed ─────────────────
   const parentSlice = getSlice(params.milestoneId, params.sliceId);
   if (!parentSlice) {
     return { error: `missing parent slice: ${params.milestoneId}/${params.sliceId}` };
   }
+  if (parentSlice.status === "complete" || parentSlice.status === "done") {
+    return { error: `cannot replan a closed slice: ${params.sliceId} (status: ${parentSlice.status})` };
+  }
+
+  // ── Verify blocker task exists and is complete ────────────────────
+  const blockerTask = getTask(params.milestoneId, params.sliceId, params.blockerTaskId);
+  if (!blockerTask) {
+    return { error: `blockerTaskId not found: ${params.milestoneId}/${params.sliceId}/${params.blockerTaskId}` };
+  }
+  if (blockerTask.status !== "complete" && blockerTask.status !== "done") {
+    return { error: `blockerTaskId ${params.blockerTaskId} is not complete (status: ${blockerTask.status}) — the blocker task must be finished before a replan is triggered` };
+  }
 
   // ── Structural enforcement ────────────────────────────────────────
   const existingTasks = getSliceTasks(params.milestoneId, params.sliceId);
@@ -136,6 +156,7 @@ export async function handleReplanSlice(
             verify: updatedTask.verify || "",
             inputs: updatedTask.inputs || [],
             expectedOutput: updatedTask.expectedOutput || [],
+            fullPlanMd: updatedTask.fullPlanMd,
           });
         } else {
           // Insert new task then set planning fields
@@ -154,6 +175,7 @@ export async function handleReplanSlice(
             verify: updatedTask.verify || "",
             inputs: updatedTask.inputs || [],
             expectedOutput: updatedTask.expectedOutput || [],
+            fullPlanMd: updatedTask.fullPlanMd,
           });
         }
       }
@@ -180,6 +202,24 @@ export async function handleReplanSlice(
     invalidateStateCache();
     clearParseCache();
 
+    // ── Post-mutation hook: projections, manifest, event log ─────
+    try {
+      await renderAllProjections(basePath, params.milestoneId);
+      writeManifest(basePath);
+      appendEvent(basePath, {
+        cmd: "replan-slice",
+        params: { milestoneId: params.milestoneId, sliceId: params.sliceId, blockerTaskId: params.blockerTaskId },
+        ts: new Date().toISOString(),
+        actor: "agent",
+        actor_name: params.actorName,
+        trigger_reason: params.triggerReason,
+      });
+    } catch (hookErr) {
+      process.stderr.write(
+        `gsd: replan-slice post-mutation hook warning: ${(hookErr as Error).message}\n`,
+      );
+    }
+
     return {
       milestoneId: params.milestoneId,
       sliceId: params.sliceId,

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