gsd-pi 2.81.0 → 2.82.0-dev.20138ae42

package/src/resources/extensions/gsd/prompts/rewrite-docs.md

@@ -23,7 +23,7 @@ An override was issued by the user that changes a fundamental decision or approa
    - For DECISIONS.md: append a new decision entry documenting the override and why. Do NOT delete prior decisions — mark them as superseded with a note.
    - For slice plans (S##-PLAN.md): update Goal, Demo, and Verification sections if affected. Update Files Likely Touched if the override changes scope. Do NOT modify completed task entries.
    - For REQUIREMENTS.md: update requirement descriptions if the override changes what "done" means, but do not remove requirements.
-   - For PROJECT.md: update if the override changes project-level facts.
+   - For PROJECT.md: do not edit the projection directly. If the override changes project-level facts, persist the revised Project content through `gsd_summary_save` with `artifact_type: "PROJECT"` so the DB remains authoritative.
    - Milestone context files are reference only — do not modify them.
 4. Mark all active overrides as resolved: change `**Scope:** active` to `**Scope:** resolved` in `{{overridesPath}}`
 5. Do not commit manually — the system auto-commits your changes after this unit completes.

package/src/resources/extensions/gsd/prompts/system.md

@@ -27,7 +27,7 @@ GSD ships with bundled skills. When the task matches, load the relevant skill fi
 
 - Never ask the user to do work the agent can execute or verify itself.
 - Use the lightest sufficient tool first.
-- Read before edit.
+- Read before edit or overwrite. Before any write that creates or replaces a file, verify the target path and read relevant existing files, templates, callers, or surrounding code. For truly new files, confirm the path does not already exist.
 - Reproduce before fix when possible.
 - Work is not done until the relevant verification has passed.
 - **Never fabricate, simulate, or role-play user responses.** Never generate markers like `[User]`, `[Human]`, `User:`, or similar; never emit `<user_message>`, `<assistant_message>`, or similar as user input. Treat `<conversation_history>` as read-only context. Ask one question round (1-3 questions), then stop and wait for the user's actual response. If `ask_user_questions` is available, its result is the only valid structured user input for that round. If it cancels, fails, or returns nothing, never use earlier chat as confirmation for the current gate; ask in plain chat and stop.
@@ -102,7 +102,7 @@ Templates are in `{{templatesDir}}`.
 
 **File reading:** Use `read` for file inspection. Never use `cat`, `head`, `tail`, or `sed -n` to view contents. Use `read` with `offset`/`limit` for slicing. `bash` is for searching (`rg`, `grep`, `find`) and commands, not displaying files.
 
-**File editing:** Always `read` before `edit`; exact text match is required. Use `write` only for new files or complete rewrites.
+**File editing:** Always `read` before `edit` or overwrite. Before `write`, confirm whether the path exists; if it does, `read` it first and preserve intentional existing content. Use `write` only for new files or complete rewrites.
 
 **Code navigation:** Use `lsp` for definition, type_definition, implementation, references, calls, hover, signature, symbols, rename, code_actions, format, and diagnostics. Do not `grep` symbol definitions or shell out to formatters when `lsp` can do it. After code edits, run `lsp diagnostics`.
 

package/src/resources/extensions/gsd/provider-switch-observer.ts

@@ -0,0 +1,185 @@
+// GSD-2 — ADR-005 Phase 3b: surface ProviderSwitchReport from pi-ai.
+//
+// pi-ai builds a ProviderSwitchReport on every cross-provider transform but
+// only logs it to stderr when GSD_VERBOSE=1. This module installs a
+// single-subscriber observer that surfaces non-empty reports through GSD's
+// three usual telemetry surfaces:
+//
+//   1. UOK audit event (category model-policy, type provider-switch) — only
+//      when an auto trace is active.
+//   2. Persistent notification (.gsd/notifications.jsonl, severity warning) —
+//      whenever the GSD basePath is known, so users see the loss in the
+//      dashboard / status surface without GSD_VERBOSE.
+//   3. In-memory counter, exposed via getProviderSwitchStats() so any
+//      caller (dashboard, doctor, tests) can read the rollup.
+
+import { setProviderSwitchObserver, type ProviderSwitchReport } from "@gsd/pi-ai";
+
+import { autoSession } from "./auto-runtime-state.js";
+import { appendNotification } from "./notification-store.js";
+import { buildAuditEnvelope, emitUokAuditEvent } from "./uok/audit.js";
+
+/** Rollup of cross-provider context transformations, grouped by trace. */
+export interface ProviderSwitchStats {
+  /** Total non-empty reports observed since process start (or last reset). */
+  totalSwitches: number;
+  /** Sum of every counted transformation across all reports. */
+  totals: {
+    thinkingBlocksDropped: number;
+    thinkingBlocksDowngraded: number;
+    toolCallIdsRemapped: number;
+    syntheticToolResultsInserted: number;
+    thoughtSignaturesDropped: number;
+  };
+  /** Per-trace breakdown. Key "interactive" covers reports outside auto-mode. */
+  byTrace: Record<string, TraceSwitchStats>;
+  /** The most recent non-empty report, if any. */
+  lastReport: ProviderSwitchReport | null;
+  /** ISO timestamp of the most recent non-empty report, if any. */
+  lastAt: string | null;
+}
+
+export interface TraceSwitchStats {
+  switches: number;
+  lastReport: ProviderSwitchReport;
+  lastAt: string;
+}
+
+const INTERACTIVE_TRACE_KEY = "interactive";
+
+interface MutableTraceStats {
+  switches: number;
+  lastReport: ProviderSwitchReport;
+  lastAt: string;
+}
+
+let installed = false;
+let totalSwitches = 0;
+const totals = {
+  thinkingBlocksDropped: 0,
+  thinkingBlocksDowngraded: 0,
+  toolCallIdsRemapped: 0,
+  syntheticToolResultsInserted: 0,
+  thoughtSignaturesDropped: 0,
+};
+const byTrace = new Map<string, MutableTraceStats>();
+let lastReport: ProviderSwitchReport | null = null;
+let lastAt: string | null = null;
+
+/** Format a one-line summary suitable for a notification message. */
+function summarize(report: ProviderSwitchReport): string {
+  const parts: string[] = [];
+  if (report.thinkingBlocksDropped > 0) parts.push(`${report.thinkingBlocksDropped} thinking dropped`);
+  if (report.thinkingBlocksDowngraded > 0) parts.push(`${report.thinkingBlocksDowngraded} thinking downgraded`);
+  if (report.toolCallIdsRemapped > 0) parts.push(`${report.toolCallIdsRemapped} tool ids remapped`);
+  if (report.syntheticToolResultsInserted > 0) parts.push(`${report.syntheticToolResultsInserted} synthetic tool results`);
+  if (report.thoughtSignaturesDropped > 0) parts.push(`${report.thoughtSignaturesDropped} thought signatures dropped`);
+  return `Provider switch ${report.fromApi} → ${report.toApi}: ${parts.join(", ")}`;
+}
+
+function recordReport(report: ProviderSwitchReport): void {
+  const now = new Date().toISOString();
+  totalSwitches += 1;
+  totals.thinkingBlocksDropped += report.thinkingBlocksDropped;
+  totals.thinkingBlocksDowngraded += report.thinkingBlocksDowngraded;
+  totals.toolCallIdsRemapped += report.toolCallIdsRemapped;
+  totals.syntheticToolResultsInserted += report.syntheticToolResultsInserted;
+  totals.thoughtSignaturesDropped += report.thoughtSignaturesDropped;
+  lastReport = report;
+  lastAt = now;
+
+  const traceKey = autoSession.currentTraceId ?? INTERACTIVE_TRACE_KEY;
+  const existing = byTrace.get(traceKey);
+  if (existing) {
+    existing.switches += 1;
+    existing.lastReport = report;
+    existing.lastAt = now;
+  } else {
+    byTrace.set(traceKey, { switches: 1, lastReport: report, lastAt: now });
+  }
+}
+
+function emitAudit(report: ProviderSwitchReport): void {
+  const traceId = autoSession.currentTraceId;
+  const basePath = autoSession.basePath;
+  if (!traceId || !basePath) return;
+  try {
+    emitUokAuditEvent(
+      basePath,
+      buildAuditEnvelope({
+        traceId,
+        category: "model-policy",
+        type: "provider-switch",
+        payload: {
+          fromApi: report.fromApi,
+          toApi: report.toApi,
+          thinkingBlocksDropped: report.thinkingBlocksDropped,
+          thinkingBlocksDowngraded: report.thinkingBlocksDowngraded,
+          toolCallIdsRemapped: report.toolCallIdsRemapped,
+          syntheticToolResultsInserted: report.syntheticToolResultsInserted,
+          thoughtSignaturesDropped: report.thoughtSignaturesDropped,
+        },
+      }),
+    );
+  } catch {
+    // Audit emission is best-effort. Counter + notification still fire.
+  }
+}
+
+function emitNotification(report: ProviderSwitchReport): void {
+  try {
+    appendNotification(summarize(report), "warning", "workflow-logger");
+  } catch {
+    // Notification persistence is best-effort.
+  }
+}
+
+function handleReport(report: ProviderSwitchReport): void {
+  recordReport(report);
+  emitAudit(report);
+  emitNotification(report);
+}
+
+/**
+ * Install the pi-ai observer. Idempotent — calling more than once is a no-op
+ * after the first install.
+ */
+export function installProviderSwitchObserver(): void {
+  if (installed) return;
+  setProviderSwitchObserver(handleReport);
+  installed = true;
+}
+
+/** Uninstall the observer. Intended for tests. */
+export function uninstallProviderSwitchObserver(): void {
+  setProviderSwitchObserver(undefined);
+  installed = false;
+}
+
+/** Read-only snapshot of the in-memory rollup. */
+export function getProviderSwitchStats(): ProviderSwitchStats {
+  const trace: Record<string, TraceSwitchStats> = {};
+  for (const [key, value] of byTrace) {
+    trace[key] = { switches: value.switches, lastReport: { ...value.lastReport }, lastAt: value.lastAt };
+  }
+  return {
+    totalSwitches,
+    totals: { ...totals },
+    byTrace: trace,
+    lastReport: lastReport ? { ...lastReport } : null,
+    lastAt,
+  };
+}
+
+/** Reset the in-memory rollup. Intended for tests. */
+export function _resetProviderSwitchStats(): void {
+  totalSwitches = 0;
+  totals.thinkingBlocksDropped = 0;
+  totals.thinkingBlocksDowngraded = 0;
+  totals.toolCallIdsRemapped = 0;
+  totals.syntheticToolResultsInserted = 0;
+  totals.thoughtSignaturesDropped = 0;
+  byTrace.clear();
+  lastReport = null;
+  lastAt = null;
+}

package/src/resources/extensions/gsd/recovery-classification.ts

@@ -2,6 +2,7 @@
 // File Purpose: ADR-015 Recovery Classification module for runtime failure taxonomy.
 
 import { classifyError, isTransient, type ErrorClass } from "./error-classifier.js";
+import { ReconciliationFailedError } from "./state-reconciliation.js";
 
 export type RecoveryFailureKind =
   | "tool-schema"
@@ -9,6 +10,7 @@ export type RecoveryFailureKind =
   | "stale-worker"
   | "worktree-invalid"
   | "verification-drift"
+  | "reconciliation-drift"
   | "provider"
   | "runtime-unknown";
 
@@ -33,7 +35,13 @@ export interface RecoveryClassification {
 
 export function classifyFailure(input: RecoveryClassificationInput): RecoveryClassification {
   const message = errorMessage(input.error);
-  const failureKind = input.failureKind ?? inferFailureKind(message);
+  // ADR-017: ReconciliationFailedError is a typed throw from the State
+  // Reconciliation Module. Recognize it by class regardless of caller-supplied
+  // failureKind so the taxonomy stays consistent.
+  const failureKind =
+    input.error instanceof ReconciliationFailedError
+      ? "reconciliation-drift"
+      : input.failureKind ?? inferFailureKind(message);
 
   switch (failureKind) {
     case "tool-schema":
@@ -76,6 +84,15 @@ export function classifyFailure(input: RecoveryClassificationInput): RecoveryCla
         exitReason: "verification-drift",
         remediation: "Inspect the verification artifact and reconcile the state snapshot before resuming.",
       };
+    case "reconciliation-drift":
+      return {
+        failureKind,
+        action: "escalate",
+        reason: `Reconciliation drift${unitSuffix(input)}: ${message}`,
+        exitReason: "reconciliation-drift",
+        remediation:
+          "Inspect the persistent or repair-failed drift kinds reported by the State Reconciliation Module before resuming.",
+      };
     case "provider": {
       const providerClass = classifyError(message, input.retryAfterMs);
       return {

package/src/resources/extensions/gsd/session-lock.ts

@@ -597,6 +597,47 @@ export function isSessionLockProcessAlive(data: SessionLockData): boolean {
   return isPidAlive(data.pid);
 }
 
+/**
+ * ADR-017 raw primitive: remove orphaned lock artifacts (lock dir + lock file)
+ * when the recorded PID is dead or no metadata is present. Mirrors the
+ * pre-flight cleanup logic in acquireSessionLock so the stale-worker drift
+ * handler can clear the orphan proactively without going through the full
+ * acquire path. No-op when the lock is held by an alive process.
+ *
+ * Returns true when artifacts were removed (drift was present).
+ */
+export function removeStaleSessionLock(basePath: string): boolean {
+  const lp = lockPath(basePath);
+  const gsdDir = gsdRoot(basePath);
+  const lockTarget = effectiveLockTarget(gsdDir);
+  const lockDir = lockTarget + ".lock";
+
+  const existingData = readExistingLockData(lp);
+  const isOrphan =
+    !existingData ||
+    (typeof existingData.pid === "number" && !isPidAlive(existingData.pid));
+  if (!isOrphan) return false;
+
+  let removed = false;
+  if (existsSync(lockDir)) {
+    try {
+      rmSync(lockDir, { recursive: true, force: true });
+      removed = true;
+    } catch {
+      /* best-effort */
+    }
+  }
+  if (existsSync(lp)) {
+    try {
+      unlinkSync(lp);
+      removed = true;
+    } catch {
+      /* best-effort */
+    }
+  }
+  return removed;
+}
+
 /**
  * Returns true if we currently hold a session lock for the given path.
  */

package/src/resources/extensions/gsd/smart-entry-routing.ts

@@ -0,0 +1,77 @@
+// GSD-2 — Smart entry routing decisions.
+// Pure route selection for /gsd guided wizard choices.
+
+export type SmartEntryIsolationMode = "worktree" | "branch" | "none";
+
+export type ActiveTaskChoice =
+  | "execute"
+  | "auto"
+  | "status"
+  | "milestone_actions";
+
+export type ActiveTaskRoute =
+  | {
+      kind: "auto-bootstrap";
+      verboseMode: false;
+      options?: {
+        step?: true;
+        milestoneLock?: string;
+      };
+    }
+  | {
+      kind: "guided-dispatch";
+      unitType: "execute-task";
+    }
+  | {
+      kind: "status";
+    }
+  | {
+      kind: "milestone-actions";
+    };
+
+export function resolveGuidedExecuteLaunchMode(
+  isolationMode: SmartEntryIsolationMode,
+): "auto-step" | "guided-dispatch" {
+  return isolationMode === "worktree" ? "auto-step" : "guided-dispatch";
+}
+
+export function resolveActiveTaskChoiceRoute(input: {
+  choice: ActiveTaskChoice;
+  isolationMode: SmartEntryIsolationMode;
+  milestoneId: string;
+}): ActiveTaskRoute {
+  if (input.choice === "auto") {
+    return {
+      kind: "auto-bootstrap",
+      verboseMode: false,
+    };
+  }
+
+  if (input.choice === "execute") {
+    if (resolveGuidedExecuteLaunchMode(input.isolationMode) === "auto-step") {
+      return {
+        kind: "auto-bootstrap",
+        verboseMode: false,
+        options: {
+          step: true,
+          milestoneLock: input.milestoneId,
+        },
+      };
+    }
+
+    return {
+      kind: "guided-dispatch",
+      unitType: "execute-task",
+    };
+  }
+
+  if (input.choice === "status") {
+    return { kind: "status" };
+  }
+
+  if (input.choice === "milestone_actions") {
+    return { kind: "milestone-actions" };
+  }
+
+  throw new Error(`Invalid ActiveTaskChoice: ${input.choice}`);
+}

package/src/resources/extensions/gsd/state-reconciliation/drift/completion.ts

@@ -0,0 +1,172 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 missing-completion-timestamp drift handler. Detects
+// tasks/slices/milestones marked complete (status = 'complete' | 'done') in
+// the DB but whose `completed_at` column is null, and where the on-disk
+// SUMMARY.md attests to completion. Backfills `completed_at` from the
+// SUMMARY.md mtime — deterministic and idempotent (re-running yields the
+// same value).
+
+import { existsSync, statSync } from "node:fs";
+
+import {
+  getMilestone,
+  getMilestoneSlices,
+  getSliceTasks,
+  isDbAvailable,
+  updateMilestoneStatus,
+  updateSliceStatus,
+  updateTaskStatus,
+} from "../../gsd-db.js";
+import {
+  resolveMilestoneFile,
+  resolveSliceFile,
+  resolveTaskFile,
+} from "../../paths.js";
+import type { GSDState } from "../../types.js";
+import type { DriftContext, DriftHandler, DriftRecord } from "../types.js";
+
+type CompletionTimestampDrift = Extract<
+  DriftRecord,
+  { kind: "missing-completion-timestamp" }
+>;
+
+const COMPLETE_STATUSES = new Set(["complete", "done"]);
+
+function summaryMtimeIso(path: string): string | null {
+  try {
+    return statSync(path).mtime.toISOString();
+  } catch {
+    return null;
+  }
+}
+
+export function detectMissingCompletionTimestampDrift(
+  state: GSDState,
+  ctx: DriftContext,
+): CompletionTimestampDrift[] {
+  if (!isDbAvailable()) return [];
+  const mid = state.activeMilestone?.id;
+  if (!mid) return [];
+
+  const milestone = getMilestone(mid);
+  if (!milestone) return [];
+
+  const drifts: CompletionTimestampDrift[] = [];
+
+  // Milestone-level
+  if (
+    COMPLETE_STATUSES.has(milestone.status) &&
+    milestone.completed_at === null
+  ) {
+    const summary = resolveMilestoneFile(ctx.basePath, mid, "SUMMARY");
+    if (summary && existsSync(summary)) {
+      drifts.push({
+        kind: "missing-completion-timestamp",
+        entity: "milestone",
+        ids: [mid],
+      });
+    }
+  }
+
+  // Slice and task levels iterate independently — tasks can complete before
+  // the parent slice closes, so task drift must be checked even when the
+  // slice is still pending.
+  for (const slice of getMilestoneSlices(mid)) {
+    if (
+      COMPLETE_STATUSES.has(slice.status) &&
+      slice.completed_at === null
+    ) {
+      const summary = resolveSliceFile(ctx.basePath, mid, slice.id, "SUMMARY");
+      if (summary && existsSync(summary)) {
+        drifts.push({
+          kind: "missing-completion-timestamp",
+          entity: "slice",
+          ids: [`${mid}/${slice.id}`],
+        });
+      }
+    }
+
+    for (const task of getSliceTasks(mid, slice.id)) {
+      if (!COMPLETE_STATUSES.has(task.status)) continue;
+      if (task.completed_at !== null) continue;
+      const taskSummary = resolveTaskFile(
+        ctx.basePath,
+        mid,
+        slice.id,
+        task.id,
+        "SUMMARY",
+      );
+      if (taskSummary && existsSync(taskSummary)) {
+        drifts.push({
+          kind: "missing-completion-timestamp",
+          entity: "task",
+          ids: [`${mid}/${slice.id}/${task.id}`],
+        });
+      }
+    }
+  }
+
+  return drifts;
+}
+
+export function repairMissingCompletionTimestamp(
+  record: CompletionTimestampDrift,
+  ctx: DriftContext,
+): void {
+  const composite = record.ids[0];
+  if (!composite) return;
+  const parts = composite.split("/");
+
+  if (record.entity === "milestone") {
+    const [mid] = parts;
+    if (!mid) return;
+    const milestone = getMilestone(mid);
+    if (
+      !milestone ||
+      milestone.completed_at !== null ||
+      !COMPLETE_STATUSES.has(milestone.status)
+    ) return;
+    const summary = resolveMilestoneFile(ctx.basePath, mid, "SUMMARY");
+    const ts = summary ? summaryMtimeIso(summary) : null;
+    if (!ts) return;
+    updateMilestoneStatus(mid, milestone.status, ts);
+    return;
+  }
+
+  if (record.entity === "slice") {
+    const [mid, sid] = parts;
+    if (!mid || !sid) return;
+    const slice = getMilestoneSlices(mid).find((s) => s.id === sid);
+    if (
+      !slice ||
+      slice.completed_at !== null ||
+      !COMPLETE_STATUSES.has(slice.status)
+    ) return;
+    const summary = resolveSliceFile(ctx.basePath, mid, sid, "SUMMARY");
+    const ts = summary ? summaryMtimeIso(summary) : null;
+    if (!ts) return;
+    updateSliceStatus(mid, sid, slice.status, ts);
+    return;
+  }
+
+  if (record.entity === "task") {
+    const [mid, sid, tid] = parts;
+    if (!mid || !sid || !tid) return;
+    const task = getSliceTasks(mid, sid).find((t) => t.id === tid);
+    if (
+      !task ||
+      task.completed_at !== null ||
+      !COMPLETE_STATUSES.has(task.status)
+    ) return;
+    const summary = resolveTaskFile(ctx.basePath, mid, sid, tid, "SUMMARY");
+    const ts = summary ? summaryMtimeIso(summary) : null;
+    if (!ts) return;
+    updateTaskStatus(mid, sid, tid, task.status, ts);
+  }
+}
+
+export const completionTimestampHandler: DriftHandler<CompletionTimestampDrift> = {
+  kind: "missing-completion-timestamp",
+  detect: detectMissingCompletionTimestampDrift,
+  repair: repairMissingCompletionTimestamp,
+};