lsd-pi 1.0.0 → 1.1.0

package/src/resources/extensions/gsd/tools/complete-task.ts

@@ -1,257 +0,0 @@
-/**
- * complete-task handler — the core operation behind gsd_complete_task.
- *
- * Validates inputs, writes task row to DB in a transaction, then (outside
- * the transaction) renders SUMMARY.md to disk, toggles the plan checkbox,
- * stores the rendered markdown in the DB for D004 recovery, and invalidates
- * caches.
- */
-
-import { join } from "node:path";
-import { mkdirSync, existsSync } from "node:fs";
-
-import type { CompleteTaskParams } from "../types.js";
-import { isClosedStatus } from "../status-guards.js";
-import {
-  transaction,
-  insertMilestone,
-  insertSlice,
-  insertTask,
-  insertVerificationEvidence,
-  getMilestone,
-  getSlice,
-  getTask,
-  updateTaskStatus,
-  setTaskSummaryMd,
-  deleteVerificationEvidence,
-} from "../gsd-db.js";
-import { resolveSliceFile, resolveTasksDir, clearPathCache } from "../paths.js";
-import { checkOwnership, taskUnitKey } from "../unit-ownership.js";
-import { saveFile, clearParseCache } from "../files.js";
-import { invalidateStateCache } from "../state.js";
-import { renderPlanCheckboxes } from "../markdown-renderer.js";
-import { renderAllProjections, renderSummaryContent } from "../workflow-projections.js";
-import { writeManifest } from "../workflow-manifest.js";
-import { appendEvent } from "../workflow-events.js";
-
-export interface CompleteTaskResult {
-  taskId: string;
-  sliceId: string;
-  milestoneId: string;
-  summaryPath: string;
-}
-
-import type { TaskRow } from "../gsd-db.js";
-
-/**
- * Build a TaskRow-shaped object from CompleteTaskParams so the unified
- * renderSummaryContent() can be used at completion time (#2720).
- */
-function paramsToTaskRow(params: CompleteTaskParams, completedAt: string): TaskRow {
-  return {
-    milestone_id: params.milestoneId,
-    slice_id: params.sliceId,
-    id: params.taskId,
-    title: params.oneLiner || params.taskId,
-    status: "complete",
-    one_liner: params.oneLiner,
-    narrative: params.narrative,
-    verification_result: params.verification,
-    duration: "",
-    completed_at: completedAt,
-    blocker_discovered: params.blockerDiscovered,
-    deviations: params.deviations,
-    known_issues: params.knownIssues,
-    key_files: params.keyFiles,
-    key_decisions: params.keyDecisions,
-    full_summary_md: "",
-    description: "",
-    estimate: "",
-    files: [],
-    verify: "",
-    inputs: [],
-    expected_output: [],
-    observability_impact: "",
-    full_plan_md: "",
-    sequence: 0,
-  };
-}
-
-/**
- * Handle the complete_task operation end-to-end.
- *
- * 1. Validate required fields
- * 2. Write DB in a transaction (milestone, slice, task, verification evidence)
- * 3. Render SUMMARY.md to disk
- * 4. Toggle plan checkbox
- * 5. Store rendered markdown back in DB (for D004 recovery)
- * 6. Invalidate caches
- */
-export async function handleCompleteTask(
-  params: CompleteTaskParams,
-  basePath: string,
-): Promise<CompleteTaskResult | { error: string }> {
-  // ── Validate required fields ────────────────────────────────────────────
-  if (!params.taskId || typeof params.taskId !== "string" || params.taskId.trim() === "") {
-    return { error: "taskId is required and must be a non-empty string" };
-  }
-  if (!params.sliceId || typeof params.sliceId !== "string" || params.sliceId.trim() === "") {
-    return { error: "sliceId is required and must be a non-empty string" };
-  }
-  if (!params.milestoneId || typeof params.milestoneId !== "string" || params.milestoneId.trim() === "") {
-    return { error: "milestoneId is required and must be a non-empty string" };
-  }
-
-  // ── Ownership check (opt-in: only enforced when claim file exists) ──────
-  const ownershipErr = checkOwnership(
-    basePath,
-    taskUnitKey(params.milestoneId, params.sliceId, params.taskId),
-    params.actorName,
-  );
-  if (ownershipErr) {
-    return { error: ownershipErr };
-  }
-
-  // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
-  const completedAt = new Date().toISOString();
-  let guardError: string | null = null;
-
-  transaction(() => {
-    // State machine preconditions (inside txn for atomicity).
-    // Milestone/slice not existing is OK — insertMilestone/insertSlice below will auto-create.
-    // Only block if they exist and are closed.
-    const milestone = getMilestone(params.milestoneId);
-    if (milestone && isClosedStatus(milestone.status)) {
-      guardError = `cannot complete task in a closed milestone: ${params.milestoneId} (status: ${milestone.status})`;
-      return;
-    }
-
-    const slice = getSlice(params.milestoneId, params.sliceId);
-    if (slice && isClosedStatus(slice.status)) {
-      guardError = `cannot complete task in a closed slice: ${params.sliceId} (status: ${slice.status})`;
-      return;
-    }
-
-    const existingTask = getTask(params.milestoneId, params.sliceId, params.taskId);
-    if (existingTask && isClosedStatus(existingTask.status)) {
-      guardError = `task ${params.taskId} is already complete — use gsd_task_reopen first if you need to redo it`;
-      return;
-    }
-
-    // All guards passed — perform writes
-    insertMilestone({ id: params.milestoneId });
-    insertSlice({ id: params.sliceId, milestoneId: params.milestoneId });
-    insertTask({
-      id: params.taskId,
-      sliceId: params.sliceId,
-      milestoneId: params.milestoneId,
-      title: params.oneLiner,
-      status: "complete",
-      oneLiner: params.oneLiner,
-      narrative: params.narrative,
-      verificationResult: params.verification,
-      duration: "",
-      blockerDiscovered: params.blockerDiscovered,
-      deviations: params.deviations,
-      knownIssues: params.knownIssues,
-      keyFiles: params.keyFiles,
-      keyDecisions: params.keyDecisions,
-    });
-
-    for (const evidence of params.verificationEvidence) {
-      insertVerificationEvidence({
-        taskId: params.taskId,
-        sliceId: params.sliceId,
-        milestoneId: params.milestoneId,
-        command: evidence.command,
-        exitCode: evidence.exitCode,
-        verdict: evidence.verdict,
-        durationMs: evidence.durationMs,
-      });
-    }
-  });
-
-  if (guardError) {
-    return { error: guardError };
-  }
-
-  // ── Filesystem operations (outside transaction) ─────────────────────────
-  // If disk render fails, roll back the DB status so deriveState() and
-  // verifyExpectedArtifact() stay consistent (both say "not done").
-
-  // Render summary markdown via the single source of truth (#2720)
-  const taskRow = paramsToTaskRow(params, completedAt);
-  const summaryMd = renderSummaryContent(taskRow, params.sliceId, params.milestoneId, params.verificationEvidence);
-
-  // Resolve and write summary to disk
-  let summaryPath: string;
-  const tasksDir = resolveTasksDir(basePath, params.milestoneId, params.sliceId);
-  if (tasksDir) {
-    summaryPath = join(tasksDir, `${params.taskId}-SUMMARY.md`);
-  } else {
-    // Tasks dir doesn't exist on disk yet — build path manually and ensure dirs
-    const gsdDir = join(basePath, ".gsd");
-    const manualTasksDir = join(gsdDir, "milestones", params.milestoneId, "slices", params.sliceId, "tasks");
-    mkdirSync(manualTasksDir, { recursive: true });
-    summaryPath = join(manualTasksDir, `${params.taskId}-SUMMARY.md`);
-  }
-
-  try {
-    await saveFile(summaryPath, summaryMd);
-
-    // Toggle plan checkbox via renderer module
-    const planPath = resolveSliceFile(basePath, params.milestoneId, params.sliceId, "PLAN");
-    if (planPath) {
-      await renderPlanCheckboxes(basePath, params.milestoneId, params.sliceId);
-    } else {
-      process.stderr.write(
-        `gsd-db: complete_task — could not find plan file for ${params.sliceId}/${params.milestoneId}, skipping checkbox toggle\n`,
-      );
-    }
-  } catch (renderErr) {
-    // Disk render failed — roll back DB status so state stays consistent
-    process.stderr.write(
-      `gsd-db: complete_task — disk render failed, rolling back DB status: ${(renderErr as Error).message}\n`,
-    );
-    // Delete orphaned verification_evidence rows first (FK constraint
-    // references tasks, so evidence must go before status change).
-    // Without this, retries accumulate duplicate evidence rows (#2724).
-    deleteVerificationEvidence(params.milestoneId, params.sliceId, params.taskId);
-    updateTaskStatus(params.milestoneId, params.sliceId, params.taskId, 'pending');
-    invalidateStateCache();
-    return { error: `disk render failed: ${(renderErr as Error).message}` };
-  }
-
-  // Store rendered markdown in DB for D004 recovery
-  setTaskSummaryMd(params.milestoneId, params.sliceId, params.taskId, summaryMd);
-
-  // Invalidate all caches
-  invalidateStateCache();
-  clearPathCache();
-  clearParseCache();
-
-  // ── Post-mutation hook: projections, manifest, event log ───────────────
-  try {
-    await renderAllProjections(basePath, params.milestoneId);
-    writeManifest(basePath);
-    appendEvent(basePath, {
-      cmd: "complete-task",
-      params: { milestoneId: params.milestoneId, sliceId: params.sliceId, taskId: params.taskId },
-      ts: new Date().toISOString(),
-      actor: "agent",
-      actor_name: params.actorName,
-      trigger_reason: params.triggerReason,
-    });
-  } catch (hookErr) {
-    process.stderr.write(
-      `gsd: complete-task post-mutation hook warning: ${(hookErr as Error).message}\n`,
-    );
-  }
-
-  return {
-    taskId: params.taskId,
-    sliceId: params.sliceId,
-    milestoneId: params.milestoneId,
-    summaryPath,
-  };
-}

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

@@ -1,304 +0,0 @@
-import { clearParseCache } from "../files.js";
-import { isClosedStatus } from "../status-guards.js";
-import { isNonEmptyString, validateStringArray } from "../validation.js";
-import {
-  transaction,
-  getMilestone,
-  getMilestoneSlices,
-  insertMilestone,
-  insertSlice,
-  upsertMilestonePlanning,
-  upsertSlicePlanning,
-} from "../gsd-db.js";
-import { invalidateStateCache } from "../state.js";
-import { renderRoadmapFromDb } from "../markdown-renderer.js";
-import { renderAllProjections } from "../workflow-projections.js";
-import { writeManifest } from "../workflow-manifest.js";
-import { appendEvent } from "../workflow-events.js";
-
-export interface PlanMilestoneSliceInput {
-  sliceId: string;
-  title: string;
-  risk: string;
-  depends: string[];
-  demo: string;
-  goal: string;
-  successCriteria: string;
-  proofLevel: string;
-  integrationClosure: string;
-  observabilityImpact: string;
-}
-
-export interface PlanMilestoneParams {
-  milestoneId: string;
-  title: string;
-  status?: string;
-  dependsOn?: string[];
-  /** Optional caller-provided identity for audit trail */
-  actorName?: string;
-  /** Optional caller-provided reason this action was triggered */
-  triggerReason?: string;
-  vision: string;
-  successCriteria: string[];
-  keyRisks: Array<{ risk: string; whyItMatters: string }>;
-  proofStrategy: Array<{ riskOrUnknown: string; retireIn: string; whatWillBeProven: string }>;
-  verificationContract: string;
-  verificationIntegration: string;
-  verificationOperational: string;
-  verificationUat: string;
-  definitionOfDone: string[];
-  requirementCoverage: string;
-  boundaryMapMarkdown: string;
-  slices: PlanMilestoneSliceInput[];
-}
-
-export interface PlanMilestoneResult {
-  milestoneId: string;
-  roadmapPath: string;
-}
-
-function validateRiskEntries(value: unknown): Array<{ risk: string; whyItMatters: string }> {
-  if (!Array.isArray(value)) {
-    throw new Error("keyRisks must be an array");
-  }
-  return value.map((entry, index) => {
-    if (!entry || typeof entry !== "object") {
-      throw new Error(`keyRisks[${index}] must be an object`);
-    }
-    const risk = (entry as Record<string, unknown>).risk;
-    const whyItMatters = (entry as Record<string, unknown>).whyItMatters;
-    if (!isNonEmptyString(risk) || !isNonEmptyString(whyItMatters)) {
-      throw new Error(`keyRisks[${index}] must include non-empty risk and whyItMatters`);
-    }
-    return { risk, whyItMatters };
-  });
-}
-
-function validateProofStrategy(value: unknown): Array<{ riskOrUnknown: string; retireIn: string; whatWillBeProven: string }> {
-  if (!Array.isArray(value)) {
-    throw new Error("proofStrategy must be an array");
-  }
-  return value.map((entry, index) => {
-    if (!entry || typeof entry !== "object") {
-      throw new Error(`proofStrategy[${index}] must be an object`);
-    }
-    const riskOrUnknown = (entry as Record<string, unknown>).riskOrUnknown;
-    const retireIn = (entry as Record<string, unknown>).retireIn;
-    const whatWillBeProven = (entry as Record<string, unknown>).whatWillBeProven;
-    if (!isNonEmptyString(riskOrUnknown) || !isNonEmptyString(retireIn) || !isNonEmptyString(whatWillBeProven)) {
-      throw new Error(`proofStrategy[${index}] must include non-empty riskOrUnknown, retireIn, and whatWillBeProven`);
-    }
-    return { riskOrUnknown, retireIn, whatWillBeProven };
-  });
-}
-
-function validateSlices(value: unknown): PlanMilestoneSliceInput[] {
-  if (!Array.isArray(value) || value.length === 0) {
-    throw new Error("slices must be a non-empty array");
-  }
-
-  const seen = new Set<string>();
-  return value.map((entry, index) => {
-    if (!entry || typeof entry !== "object") {
-      throw new Error(`slices[${index}] must be an object`);
-    }
-    const obj = entry as Record<string, unknown>;
-    const sliceId = obj.sliceId;
-    const title = obj.title;
-    const risk = obj.risk;
-    const depends = obj.depends;
-    const demo = obj.demo;
-    const goal = obj.goal;
-    const successCriteria = obj.successCriteria;
-    const proofLevel = obj.proofLevel;
-    const integrationClosure = obj.integrationClosure;
-    const observabilityImpact = obj.observabilityImpact;
-
-    if (!isNonEmptyString(sliceId)) throw new Error(`slices[${index}].sliceId must be a non-empty string`);
-    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`);
-    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`);
-    }
-    if (!isNonEmptyString(demo)) throw new Error(`slices[${index}].demo must be a non-empty string`);
-    if (!isNonEmptyString(goal)) throw new Error(`slices[${index}].goal must be a non-empty string`);
-    if (!isNonEmptyString(successCriteria)) throw new Error(`slices[${index}].successCriteria must be a non-empty string`);
-    if (!isNonEmptyString(proofLevel)) throw new Error(`slices[${index}].proofLevel must be a non-empty string`);
-    if (!isNonEmptyString(integrationClosure)) throw new Error(`slices[${index}].integrationClosure must be a non-empty string`);
-    if (!isNonEmptyString(observabilityImpact)) throw new Error(`slices[${index}].observabilityImpact must be a non-empty string`);
-
-    return {
-      sliceId,
-      title,
-      risk,
-      depends,
-      demo,
-      goal,
-      successCriteria,
-      proofLevel,
-      integrationClosure,
-      observabilityImpact,
-    };
-  });
-}
-
-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");
-  if (!isNonEmptyString(params?.verificationContract)) throw new Error("verificationContract is required");
-  if (!isNonEmptyString(params?.verificationIntegration)) throw new Error("verificationIntegration is required");
-  if (!isNonEmptyString(params?.verificationOperational)) throw new Error("verificationOperational is required");
-  if (!isNonEmptyString(params?.verificationUat)) throw new Error("verificationUat is required");
-  if (!isNonEmptyString(params?.requirementCoverage)) throw new Error("requirementCoverage is required");
-  if (!isNonEmptyString(params?.boundaryMapMarkdown)) throw new Error("boundaryMapMarkdown is required");
-
-  return {
-    ...params,
-    dependsOn: params.dependsOn ? validateStringArray(params.dependsOn, "dependsOn") : [],
-    successCriteria: validateStringArray(params.successCriteria, "successCriteria"),
-    keyRisks: validateRiskEntries(params.keyRisks),
-    proofStrategy: validateProofStrategy(params.proofStrategy),
-    definitionOfDone: validateStringArray(params.definitionOfDone, "definitionOfDone"),
-    slices: validateSlices(params.slices),
-  };
-}
-
-export async function handlePlanMilestone(
-  rawParams: PlanMilestoneParams,
-  basePath: string,
-): Promise<PlanMilestoneResult | { error: string }> {
-  let params: PlanMilestoneParams;
-  try {
-    params = validateParams(rawParams);
-  } catch (err) {
-    return { error: `validation failed: ${(err as Error).message}` };
-  }
-
-  // ── 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;
-
-  try {
-    transaction(() => {
-      const existingMilestone = getMilestone(params.milestoneId);
-      if (existingMilestone && isClosedStatus(existingMilestone.status)) {
-        guardError = `cannot re-plan milestone ${params.milestoneId}: it is already complete`;
-        return;
-      }
-
-      // Guard: refuse to re-plan a milestone that has completed slices (#2960).
-      // INSERT OR IGNORE on slices won't overwrite existing rows, but a full
-      // re-plan after worktree recreation or DB resync can create new slice rows
-      // that shadow completed work. Block early when any slice is already done.
-      const existingSlices = getMilestoneSlices(params.milestoneId);
-      const completedSlices = existingSlices.filter(s => isClosedStatus(s.status));
-      if (completedSlices.length > 0) {
-        guardError = `cannot re-plan milestone ${params.milestoneId}: ${completedSlices.length} slice(s) already completed (${completedSlices.map(s => s.id).join(", ")}). Use gsd_reassess_roadmap to modify the roadmap.`;
-        return;
-      }
-
-      // Validate depends_on: all dependencies must exist and be complete
-      if (params.dependsOn && params.dependsOn.length > 0) {
-        for (const depId of params.dependsOn) {
-          const dep = getMilestone(depId);
-          if (!dep) {
-            guardError = `depends_on references unknown milestone: ${depId}`;
-            return;
-          }
-          if (!isClosedStatus(dep.status)) {
-            guardError = `depends_on milestone ${depId} is not yet complete (status: ${dep.status})`;
-            return;
-          }
-        }
-      }
-
-      insertMilestone({
-        id: params.milestoneId,
-        title: params.title,
-        status: params.status ?? "active",
-        depends_on: params.dependsOn ?? [],
-      });
-
-      upsertMilestonePlanning(params.milestoneId, {
-        vision: params.vision,
-        successCriteria: params.successCriteria,
-        keyRisks: params.keyRisks,
-        proofStrategy: params.proofStrategy,
-        verificationContract: params.verificationContract,
-        verificationIntegration: params.verificationIntegration,
-        verificationOperational: params.verificationOperational,
-        verificationUat: params.verificationUat,
-        definitionOfDone: params.definitionOfDone,
-        requirementCoverage: params.requirementCoverage,
-        boundaryMapMarkdown: params.boundaryMapMarkdown,
-      }, params.title);
-
-      for (const slice of params.slices) {
-        insertSlice({
-          id: slice.sliceId,
-          milestoneId: params.milestoneId,
-          title: slice.title,
-          status: "pending",
-          risk: slice.risk,
-          depends: slice.depends,
-          demo: slice.demo,
-        });
-        upsertSlicePlanning(params.milestoneId, slice.sliceId, {
-          goal: slice.goal,
-          successCriteria: slice.successCriteria,
-          proofLevel: slice.proofLevel,
-          integrationClosure: slice.integrationClosure,
-          observabilityImpact: slice.observabilityImpact,
-        });
-      }
-    });
-  } catch (err) {
-    return { error: `db write failed: ${(err as Error).message}` };
-  }
-
-  if (guardError) {
-    return { error: guardError };
-  }
-
-  let roadmapPath: string;
-  try {
-    const renderResult = await renderRoadmapFromDb(basePath, params.milestoneId);
-    roadmapPath = renderResult.roadmapPath;
-  } catch (renderErr) {
-    process.stderr.write(
-      `gsd-db: plan_milestone — render failed (DB rows preserved for debugging): ${(renderErr as Error).message}\n`,
-    );
-    invalidateStateCache();
-    return { error: `render failed: ${(renderErr as Error).message}` };
-  }
-
-  invalidateStateCache();
-  clearParseCache();
-
-  // ── Post-mutation hook: projections, manifest, event log ───────────────
-  try {
-    await renderAllProjections(basePath, params.milestoneId);
-    writeManifest(basePath);
-    appendEvent(basePath, {
-      cmd: "plan-milestone",
-      params: { milestoneId: params.milestoneId },
-      ts: new Date().toISOString(),
-      actor: "agent",
-      actor_name: params.actorName,
-      trigger_reason: params.triggerReason,
-    });
-  } catch (hookErr) {
-    process.stderr.write(
-      `gsd: plan-milestone post-mutation hook warning: ${(hookErr as Error).message}\n`,
-    );
-  }
-
-  return {
-    milestoneId: params.milestoneId,
-    roadmapPath,
-  };
-}