gsd-pi 2.79.0-dev.ece5fd8ba → 2.80.0-dev.0aaa4fc17

package/src/resources/extensions/gsd/tests/worktree-write-gate.test.ts

@@ -0,0 +1,179 @@
+// GSD-2 worktree-isolation write gate (#5199).
+//
+// Regression coverage for shouldBlockWorktreeWrite — the helper that prevents
+// the LLM from authoring code at the project root when `git.isolation: worktree`
+// is configured but auto-mode (and its post-unit commit pipeline) hasn't run.
+// Without this gate, writes silently orphan outside git history.
+//
+// Test setup creates a fresh temp project for each isolation case, writes a
+// `.gsd/PREFERENCES.md` with `isolation: "worktree"`, and exercises the helper
+// against the 9 scenarios listed in the issue. No source-grep tests — every
+// assertion exercises the real predicate.
+
+import { test, describe, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { shouldBlockWorktreeWrite } from "../bootstrap/write-gate.js";
+import { invalidateAllCaches } from "../cache.js";
+
+function makeProject(isolation: "none" | "worktree" | "branch" | null): string {
+  const root = mkdtempSync(join(tmpdir(), "wt-write-gate-"));
+  if (isolation !== null) {
+    mkdirSync(join(root, ".gsd"), { recursive: true });
+    writeFileSync(
+      join(root, ".gsd", "PREFERENCES.md"),
+      `---\ngit:\n  isolation: "${isolation}"\n---\n`,
+    );
+  }
+  invalidateAllCaches();
+  return root;
+}
+
+const PLANNING_WRITE_TOOLS = ["write", "edit", "multi_edit", "notebook_edit"];
+
+describe("shouldBlockWorktreeWrite (#5199)", () => {
+  let projectRoot: string;
+  let prevDisableEnv: string | undefined;
+
+  beforeEach(() => {
+    prevDisableEnv = process.env.GSD_DISABLE_WORKTREE_WRITE_GUARD;
+    delete process.env.GSD_DISABLE_WORKTREE_WRITE_GUARD;
+  });
+
+  afterEach(() => {
+    if (projectRoot) {
+      try { rmSync(projectRoot, { recursive: true, force: true }); } catch { /* best-effort */ }
+    }
+    if (prevDisableEnv === undefined) {
+      delete process.env.GSD_DISABLE_WORKTREE_WRITE_GUARD;
+    } else {
+      process.env.GSD_DISABLE_WORKTREE_WRITE_GUARD = prevDisableEnv;
+    }
+    invalidateAllCaches();
+  });
+
+  test("Case 1: every PLANNING_WRITE_TOOLS variant writing to <root>/app.js is blocked", () => {
+    projectRoot = makeProject("worktree");
+    for (const tool of PLANNING_WRITE_TOOLS) {
+      const result = shouldBlockWorktreeWrite(
+        tool,
+        join(projectRoot, "app.js"),
+        projectRoot,
+        /* isAutoLive */ false,
+        /* unitType */ null,
+      );
+      assert.equal(result.block, true, `tool ${tool} should be blocked`);
+      assert.match(result.reason ?? "", /HARD BLOCK/);
+    }
+  });
+
+  test("Case 2: write to <root>/.gsd/PROJECT.md is allowed", () => {
+    projectRoot = makeProject("worktree");
+    const result = shouldBlockWorktreeWrite(
+      "write",
+      join(projectRoot, ".gsd", "PROJECT.md"),
+      projectRoot,
+      false,
+      null,
+    );
+    assert.equal(result.block, false);
+  });
+
+  test("Case 3: write inside <root>/.gsd/worktrees/M001/ is allowed", () => {
+    projectRoot = makeProject("worktree");
+    const target = join(projectRoot, ".gsd", "worktrees", "M001", "src", "app.js");
+    const result = shouldBlockWorktreeWrite("edit", target, projectRoot, false, null);
+    assert.equal(result.block, false);
+  });
+
+  test("Case 4: write to <root>/.gsd/worktrees-extra/M001/app.js (prefix trick) is blocked", () => {
+    projectRoot = makeProject("worktree");
+    const target = join(projectRoot, ".gsd", "worktrees-extra", "M001", "app.js");
+    const result = shouldBlockWorktreeWrite("write", target, projectRoot, false, null);
+    assert.equal(result.block, true);
+    assert.match(result.reason ?? "", /HARD BLOCK/);
+  });
+
+  test("Case 5: isolation=none → allow", () => {
+    projectRoot = makeProject("none");
+    const result = shouldBlockWorktreeWrite(
+      "write",
+      join(projectRoot, "app.js"),
+      projectRoot,
+      false,
+      null,
+    );
+    assert.equal(result.block, false);
+  });
+
+  test("Case 6: isolation=worktree, auto active, effectiveBasePath inside worktree → allow", () => {
+    projectRoot = makeProject("worktree");
+    const inside = join(projectRoot, ".gsd", "worktrees", "M001");
+    mkdirSync(inside, { recursive: true });
+    const result = shouldBlockWorktreeWrite(
+      "write",
+      join(inside, "src", "app.js"),
+      inside,
+      /* isAutoLive */ true,
+      null,
+    );
+    assert.equal(result.block, false);
+  });
+
+  test("Case 7: isolation=worktree, auto active, effectiveBasePath is project root (cwd never flipped) → block", () => {
+    projectRoot = makeProject("worktree");
+    const result = shouldBlockWorktreeWrite(
+      "write",
+      join(projectRoot, "app.js"),
+      projectRoot,
+      /* isAutoLive */ true,
+      null,
+    );
+    assert.equal(result.block, true);
+    assert.match(result.reason ?? "", /HARD BLOCK/);
+  });
+
+  test("Case 8: bootstrap unit type active → allow", () => {
+    projectRoot = makeProject("worktree");
+    for (const unitType of ["discuss-milestone", "plan-milestone", "init"]) {
+      const result = shouldBlockWorktreeWrite(
+        "write",
+        join(projectRoot, "app.js"),
+        projectRoot,
+        false,
+        unitType,
+      );
+      assert.equal(result.block, false, `unit ${unitType} should bypass the guard`);
+    }
+  });
+
+  test("Case 9: GSD_DISABLE_WORKTREE_WRITE_GUARD=1 → allow", () => {
+    projectRoot = makeProject("worktree");
+    process.env.GSD_DISABLE_WORKTREE_WRITE_GUARD = "1";
+    const result = shouldBlockWorktreeWrite(
+      "write",
+      join(projectRoot, "app.js"),
+      projectRoot,
+      false,
+      null,
+    );
+    assert.equal(result.block, false);
+  });
+
+  test("non-planning tools (read/grep/bash) pass through unconditionally", () => {
+    projectRoot = makeProject("worktree");
+    for (const tool of ["read", "grep", "bash", "ls"]) {
+      const result = shouldBlockWorktreeWrite(
+        tool,
+        join(projectRoot, "app.js"),
+        projectRoot,
+        false,
+        null,
+      );
+      assert.equal(result.block, false, `tool ${tool} must not be gated`);
+    }
+  });
+});

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

@@ -1,3 +1,4 @@
+// GSD2 complete-milestone tool handler
 /**
  * complete-milestone handler — the core operation behind gsd_complete_milestone.
  *
@@ -57,6 +58,7 @@ export interface CompleteMilestoneResult {
   milestoneId: string;
   summaryPath: string;
   stale?: boolean;
+  alreadyComplete?: boolean;
 }
 
 function renderMilestoneSummaryMarkdown(params: CompleteMilestoneParams): string {
@@ -143,6 +145,7 @@ export async function handleCompleteMilestone(
   // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
   const completedAt = new Date().toISOString();
   let guardError: string | null = null;
+  let alreadyComplete = false;
 
   transaction(() => {
     // State machine preconditions (inside txn for atomicity)
@@ -152,7 +155,7 @@ export async function handleCompleteMilestone(
       return;
     }
     if (isClosedStatus(milestone.status)) {
-      guardError = `milestone ${params.milestoneId} is already complete`;
+      alreadyComplete = true;
       return;
     }
 
@@ -238,14 +241,16 @@ export async function handleCompleteMilestone(
     logWarning("tool", `complete-milestone manifest warning: ${(mfErr as Error).message}`);
   }
   try {
-    appendEvent(basePath, {
-      cmd: "complete-milestone",
-      params: { milestoneId: params.milestoneId },
-      ts: new Date().toISOString(),
-      actor: "agent",
-      actor_name: params.actorName,
-      trigger_reason: params.triggerReason,
-    });
+    if (!alreadyComplete) {
+      appendEvent(basePath, {
+        cmd: "complete-milestone",
+        params: { milestoneId: params.milestoneId },
+        ts: new Date().toISOString(),
+        actor: "agent",
+        actor_name: params.actorName,
+        trigger_reason: params.triggerReason,
+      });
+    }
   } catch (eventErr) {
     logError("tool", `complete-milestone event log FAILED — completion invisible to reconciliation`, { error: (eventErr as Error).message });
   }
@@ -254,5 +259,6 @@ export async function handleCompleteMilestone(
     milestoneId: params.milestoneId,
     summaryPath,
     ...(projectionStale ? { stale: true } : {}),
+    ...(alreadyComplete ? { alreadyComplete: true } : {}),
   };
 }

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

@@ -1,3 +1,6 @@
+// Project/App: GSD-2
+// File Purpose: Complete-task tool handler for GSD workflow state and summaries.
+
 /**
  * complete-task handler — the core operation behind gsd_complete_task.
  *
@@ -55,7 +58,7 @@ export interface CompleteTaskResult {
   stale?: boolean;
 }
 
-import type { TaskRow } from "../gsd-db.js";
+import type { TaskRow } from "../db-task-slice-rows.js";
 
 /**
  * Map an execute-task-owned gate id to the CompleteTaskParams field whose

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

@@ -18,6 +18,7 @@ import { renderAllProjections } from "../workflow-projections.js";
 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";
 
 export interface PlanSliceTaskInput {
   taskId: string;
@@ -141,6 +142,18 @@ export async function handlePlanSlice(
     return { error: `validation failed: ${(err as Error).message}` };
   }
 
+  const pathScopeError = validatePlanningPathScope(
+    basePath,
+    params.tasks.flatMap((task, index) => [
+      { field: `tasks[${index}].files`, values: task.files },
+      { field: `tasks[${index}].inputs`, values: task.inputs },
+      { field: `tasks[${index}].expectedOutput`, values: task.expectedOutput },
+    ]),
+  );
+  if (pathScopeError) {
+    return { error: `validation failed: ${pathScopeError}` };
+  }
+
   // ── 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).

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

@@ -8,6 +8,7 @@ import { renderAllProjections } from "../workflow-projections.js";
 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";
 
 export interface PlanTaskParams {
   milestoneId: string;
@@ -66,6 +67,15 @@ export async function handlePlanTask(
     return { error: `validation failed: ${(err as Error).message}` };
   }
 
+  const pathScopeError = validatePlanningPathScope(basePath, [
+    { field: "files", values: params.files },
+    { field: "inputs", values: params.inputs },
+    { field: "expectedOutput", values: params.expectedOutput },
+  ]);
+  if (pathScopeError) {
+    return { error: `validation failed: ${pathScopeError}` };
+  }
+
   // ── 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).

package/src/resources/extensions/gsd/tools/workflow-tool-executors.ts

@@ -477,12 +477,17 @@ export async function executeCompleteMilestone(
       isError: true,
       };
     }
+    const message = result.alreadyComplete
+      ? `Milestone ${result.milestoneId} is already complete. Summary available at ${result.summaryPath}`
+      : `Completed milestone ${result.milestoneId}. Summary written to ${result.summaryPath}`;
     return {
-      content: [{ type: "text", text: `Completed milestone ${result.milestoneId}. Summary written to ${result.summaryPath}` }],
+      content: [{ type: "text", text: message }],
       details: {
         operation: "complete_milestone",
         milestoneId: result.milestoneId,
         summaryPath: result.summaryPath,
+        ...(result.alreadyComplete ? { alreadyComplete: true } : {}),
+        ...(result.stale ? { stale: true } : {}),
       },
     };
   } catch (err) {

package/src/resources/extensions/gsd/unit-context-composer.ts

@@ -113,7 +113,7 @@ const CONTEXT_MODE_LANE_LABELS: Record<Exclude<ContextModePolicy, "none">, strin
 };
 
 const CONTEXT_MODE_GUIDANCE =
-  "Use `gsd_exec` for noisy scans, builds, and tests so full output stays out of prompt context; call `gsd_exec_search` before repeating prior runs; call `gsd_resume` after compaction or resume to recover stored execution context.";
+  "Use `gsd_exec` for noisy commands, `gsd_exec_search` before reruns, and `gsd_resume` after compaction or resume.";
 
 /**
  * Render the Context Mode instruction lane for a unit type. Unknown unit

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

@@ -67,11 +67,25 @@ export type UnitRuntimePhase =
   | "wrapup-warning-sent"
   | "timeout"
   | "finalize-timeout"
+  | "crashed"
   | "recovered"
   | "finalized"
   | "paused"
   | "skipped";
 
+export const IN_FLIGHT_RUNTIME_PHASES: ReadonlySet<UnitRuntimePhase> = new Set([
+  "dispatched",
+  "wrapup-warning-sent",
+  "timeout",
+  "finalize-timeout",
+  "crashed",
+  "paused",
+]);
+
+export function isInFlightRuntimePhase(phase: UnitRuntimePhase): boolean {
+  return IN_FLIGHT_RUNTIME_PHASES.has(phase);
+}
+
 export interface ExecuteTaskRecoveryStatus {
   planPath: string;
   summaryPath: string;

package/src/resources/extensions/gsd/uok/kernel.ts

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Selects the UOK kernel path and records parity diagnostics.
 import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 import { appendFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
@@ -9,6 +11,7 @@ import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
 import { setUnifiedAuditEnabled } from "./audit-toggle.js";
 import { resolveUokFlags } from "./flags.js";
 import { createTurnObserver } from "./loop-adapter.js";
+import { incrementLegacyTelemetry } from "../legacy-telemetry.js";
 
 interface RunAutoLoopWithUokArgs {
   ctx: ExtensionContext;
@@ -54,10 +57,14 @@ export async function runAutoLoopWithUok(args: RunAutoLoopWithUokArgs): Promise<
   const prefs = deps.loadEffectiveGSDPreferences()?.preferences;
   const flags = resolveUokFlags(prefs);
   setUnifiedAuditEnabled(flags.auditUnified);
+  const pathLabel = resolveKernelPathLabel(flags);
+  if (pathLabel !== "uok-kernel") {
+    incrementLegacyTelemetry("legacy.uokFallbackUsed");
+  }
 
   writeParityEvent(s.basePath, {
     ts: new Date().toISOString(),
-    path: resolveKernelPathLabel(flags),
+    path: pathLabel,
     flags,
     phase: "enter",
   });
@@ -98,7 +105,7 @@ export async function runAutoLoopWithUok(args: RunAutoLoopWithUokArgs): Promise<
     }
     writeParityEvent(s.basePath, {
       ts: new Date().toISOString(),
-      path: resolveKernelPathLabel(flags),
+      path: pathLabel,
       flags,
       phase: "exit",
       status: "ok",
@@ -106,7 +113,7 @@ export async function runAutoLoopWithUok(args: RunAutoLoopWithUokArgs): Promise<
   } catch (err) {
     writeParityEvent(s.basePath, {
       ts: new Date().toISOString(),
-      path: resolveKernelPathLabel(flags),
+      path: pathLabel,
       flags,
       phase: "exit",
       status: "error",

package/src/resources/extensions/gsd/uok/plan-v2.ts

@@ -1,9 +1,13 @@
+// Project/App: GSD-2
+// File Purpose: UOK plan v2 graph compilation from GSD workflow state.
+
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 import type { GSDState, Phase } from "../types.js";
 import { gsdRoot, resolveMilestoneFile, resolveSliceFile } from "../paths.js";
-import { isDbAvailable, getMilestoneSlices, getSliceTasks, type SliceRow } from "../gsd-db.js";
+import { isDbAvailable, getMilestoneSlices, getSliceTasks } from "../gsd-db.js";
+import type { SliceRow } from "../db-task-slice-rows.js";
 import type { UokGraphNode } from "./contracts.js";
 
 const PLAN_V2_CLARIFY_ROUND_LIMIT = 3;

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

@@ -3,13 +3,12 @@
 // Captures structured entries that the auto-loop can drain after each unit
 // to surface root causes for stuck loops, silent degradation, and blocked writes.
 // Error-severity entries are persisted to .gsd/audit-log.jsonl (sanitized) for
-// post-mortem analysis. Warnings are ephemeral (stderr + buffer only) to avoid
-// log amplification from expected-control-flow catch paths.
+// post-mortem analysis. Warnings persist to notifications and remain available
+// in the in-memory buffer, but are not printed to stderr.
 //
-// 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.
+// Stderr policy: logError writes immediately to stderr for terminal visibility.
+// logWarning stays out of the TUI/stdout stream and is surfaced through the
+// notification store plus the auto-loop issue buffer.
 //
 // Singleton safety: _buffer is module-level and shared across all calls within
 // a process. The auto-loop must call _resetLogs() (or drainAndSummarize()) at
@@ -109,7 +108,8 @@ export function setStderrLoggingEnabled(enabled: boolean): boolean {
 // ─── Public API ─────────────────────────────────────────────────────────
 
 /**
- * Record a warning. Also writes to stderr for terminal visibility.
+ * Record a warning. Warnings are persisted to notifications and buffered for
+ * auto-loop issue summaries, but they are intentionally not written to stderr.
  */
 export function logWarning(
   component: LogComponent,
@@ -271,10 +271,10 @@ function _push(
     ...(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)}` : "";
-  _writeStderr(`[gsd:${component}] ${prefix}: ${message}${ctxStr}\n`);
+  if (severity === "error") {
+    const ctxStr = context ? ` ${JSON.stringify(context)}` : "";
+    _writeStderr(`[gsd:${component}] ERROR: ${message}${ctxStr}\n`);
+  }
 
   // Persist to notification store (both warnings and errors)
   try {
@@ -317,8 +317,8 @@ function _push(
   }
 
   // Persist errors to .gsd/audit-log.jsonl so they survive context resets.
-  // Only error-severity entries are persisted — warnings are ephemeral (stderr + buffer)
-  // to avoid log amplification from expected-control-flow catch paths.
+  // Warnings are already persisted to notifications and buffered for the
+  // current auto-loop unit.
   if (_auditBasePath && severity === "error") {
     try {
       const auditDir = join(_auditBasePath, ".gsd");

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

@@ -1,11 +1,14 @@
+// Project/App: GSD-2
+// File Purpose: State manifest snapshot and restore orchestration for GSD workflow data.
+
 import {
   _getAdapter,
   readTransaction,
   restoreManifest,
-  type MilestoneRow,
-  type SliceRow,
-  type TaskRow,
 } from "./gsd-db.js";
+import type { MilestoneRow } from "./db-milestone-artifact-rows.js";
+import type { SliceRow, TaskRow } from "./db-task-slice-rows.js";
+import type { VerificationEvidenceRow } from "./db-verification-evidence-rows.js";
 import type { Decision } from "./types.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import { readFileSync, existsSync, mkdirSync } from "node:fs";
@@ -13,18 +16,6 @@ import { join } from "node:path";
 
 // ─── Manifest Types ──────────────────────────────────────────────────────
 
-export interface VerificationEvidenceRow {
-  id: number;
-  task_id: string;
-  slice_id: string;
-  milestone_id: string;
-  command: string;
-  exit_code: number | null;
-  verdict: string;
-  duration_ms: number | null;
-  created_at: string;
-}
-
 export interface StateManifest {
   version: 1;
   exported_at: string; // ISO 8601

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

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Projection renderers for GSD workflow database rows.
 // GSD Extension — Projection Renderers (DB -> Markdown)
 // Renders PLAN.md, ROADMAP.md, SUMMARY.md, and STATE.md from database rows.
 // Projections are read-only views of engine state (Layer 3 of the architecture).
@@ -11,7 +13,9 @@ import {
   getSliceTasks,
   getVerificationEvidence,
 } from "./gsd-db.js";
-import type { MilestoneRow, SliceRow, TaskRow, VerificationEvidenceRow } from "./gsd-db.js";
+import type { MilestoneRow } from "./db-milestone-artifact-rows.js";
+import type { SliceRow, TaskRow } from "./db-task-slice-rows.js";
+import type { VerificationEvidenceRow } from "./db-verification-evidence-rows.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import { join } from "node:path";
 import { mkdirSync, existsSync } from "node:fs";

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

@@ -1,3 +1,6 @@
+// Project/App: GSD-2
+// File Purpose: Workflow template registry loading, matching, and display helpers.
+
 /**
  * GSD Workflow Templates — Registry & Resolution
  *
@@ -9,6 +12,7 @@ import { readFileSync, existsSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { gsdHome } from "./gsd-home.js";
+import { formatRecommendedProcessPaths } from "./process-task-path.js";
 
 const __extensionDir = resolveGsdExtensionDir();
 const registryPath = join(__extensionDir, "workflow-templates", "registry.json");
@@ -30,6 +34,10 @@ export type WorkflowMode =
   | "markdown-phase"
   | "auto-milestone";
 
+export function isLegacyWorkflowMode(mode: WorkflowMode | undefined): boolean {
+  return (mode ?? "markdown-phase") !== "auto-milestone";
+}
+
 export interface TemplateEntry {
   name: string;
   description: string;
@@ -213,6 +221,9 @@ export function listTemplates(): string {
 
   lines.push("Usage: /gsd start <template> [description]");
   lines.push("       /gsd templates info <name>");
+  lines.push("");
+  lines.push("Recommended Task Paths:");
+  lines.push(formatRecommendedProcessPaths());
 
   return lines.join("\n");
 }