gsd-pi 2.76.0 → 2.77.0-dev.538325aea

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

@@ -38,6 +38,29 @@ function hasFileContent(path: string | null): boolean {
   }
 }
 
+function getArtifactLookupBases(basePath: string): string[] {
+  const bases = [basePath];
+  const projectRoot = process.env.GSD_PROJECT_ROOT;
+  if (projectRoot && projectRoot.trim().length > 0 && projectRoot !== basePath) {
+    bases.push(projectRoot);
+  }
+  return bases;
+}
+
+function hasMilestoneFileContent(
+  basePath: string,
+  milestoneId: string,
+  suffix: string,
+): boolean {
+  const bases = getArtifactLookupBases(basePath);
+  for (const candidateBase of bases) {
+    if (hasFileContent(resolveMilestoneFile(candidateBase, milestoneId, suffix))) {
+      return true;
+    }
+  }
+  return false;
+}
+
 function countSliceResearchArtifacts(basePath: string, milestoneId: string, slices: SliceRow[]): number {
   let count = 0;
   for (const slice of slices) {
@@ -60,9 +83,9 @@ export function compileUnitGraphFromState(basePath: string, state: GSDState): Pl
   const slices = getMilestoneSlices(mid).sort((a, b) => Number(a.sequence ?? 0) - Number(b.sequence ?? 0));
   const nodes: UokGraphNode[] = [];
   const clarifyRoundLimit = PLAN_V2_CLARIFY_ROUND_LIMIT;
-  const draftContextIncluded = hasFileContent(resolveMilestoneFile(basePath, mid, "CONTEXT-DRAFT"));
-  const finalizedContextIncluded = hasFileContent(resolveMilestoneFile(basePath, mid, "CONTEXT"));
-  const researchSynthesized = hasFileContent(resolveMilestoneFile(basePath, mid, "RESEARCH"))
+  const draftContextIncluded = hasMilestoneFileContent(basePath, mid, "CONTEXT-DRAFT");
+  const finalizedContextIncluded = hasMilestoneFileContent(basePath, mid, "CONTEXT");
+  const researchSynthesized = hasMilestoneFileContent(basePath, mid, "RESEARCH")
     || countSliceResearchArtifacts(basePath, mid, slices) > 0;
 
   if (isExecutionEntryPhase(state.phase) && !finalizedContextIncluded) {

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

@@ -56,7 +56,10 @@ export type LogComponent =
   | "safety"        // LLM safety harness
   | "ecosystem"     // GSD ecosystem extension loader and dispatch
   | "memory-embeddings" // Memory layer embedding generation
-  | "memory-ingest";    // Memory layer ingestion pipeline
+  | "memory-ingest"     // Memory layer ingestion pipeline
+  | "memory-backfill"   // ADR-013: decisions->memories backfill
+  | "context-mode"     // Context-mode exec sandbox and compaction snapshot
+  | "preflight";       // Clean-root preflight gate at milestone completion
 
 export interface LogEntry {
   ts: string;

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

@@ -23,6 +23,9 @@ export interface WorkflowCapabilityOptions {
 const MCP_WORKFLOW_TOOL_SURFACE = new Set([
   "ask_user_questions",
   "gsd_decision_save",
+  "gsd_exec",
+  "gsd_exec_search",
+  "gsd_resume",
   "gsd_complete_milestone",
   "gsd_complete_task",
   "gsd_complete_slice",

package/src/resources/extensions/gsd/workflow-templates/spike.md

@@ -66,5 +66,11 @@ Use for: technology evaluation, architecture decisions, "should we X?" questions
    - Recommendation with rationale
    - Next steps if the recommendation is accepted
 4. **Present** the recommendation to the user for discussion
+5. **Offer wrap-up:** If the findings are reusable on future work, offer to run
+   the `spike-wrap-up` skill to package them as a project-local skill at
+   `.claude/skills/<name>/SKILL.md`. That skill will auto-load on future
+   similar tasks via `skill-discovery.ts`. If the recommendation is
+   decision-only (no reusable guidance), suggest appending a one-liner to
+   `.gsd/DECISIONS.md` instead.
 
 </process>

package/src/resources/extensions/gsd/worktree-resolver.ts

@@ -79,6 +79,35 @@ export interface NotifyCtx {
   ) => void;
 }
 
+// ─── Path Helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Worktree marker segment — present in any path produced by worktreePath().
+ * Used to strip the worktree suffix and recover the project root (#3729).
+ */
+const WORKTREE_MARKER = "/.gsd/worktrees/";
+
+/**
+ * Resolve the project root from session path state.
+ *
+ * Prefers `originalBasePath` (always the project root when set), but falls
+ * back to `basePath` when `originalBasePath` is falsy (e.g. fresh AutoSession
+ * with default empty string). If `basePath` itself is inside a worktree
+ * directory (contains `/.gsd/worktrees/`), strip that suffix to recover the
+ * actual project root — preventing double-nested worktree paths (#3729).
+ */
+export function resolveProjectRoot(
+  originalBasePath: string,
+  basePath: string,
+): string {
+  let resolved = originalBasePath || basePath;
+  const markerIdx = resolved.indexOf(WORKTREE_MARKER);
+  if (markerIdx !== -1) {
+    resolved = resolved.slice(0, markerIdx);
+  }
+  return resolved;
+}
+
 // ─── WorktreeResolver ──────────────────────────────────────────────────────
 
 export class WorktreeResolver {
@@ -99,12 +128,12 @@ export class WorktreeResolver {
 
   /** Original project root — always the non-worktree path. */
   get projectRoot(): string {
-    return this.s.originalBasePath || this.s.basePath;
+    return resolveProjectRoot(this.s.originalBasePath, this.s.basePath);
   }
 
   /** Path for auto.lock file — same as the old lockBase(). */
   get lockPath(): string {
-    return this.s.originalBasePath || this.s.basePath;
+    return resolveProjectRoot(this.s.originalBasePath, this.s.basePath);
   }
 
   // ── Private Helpers ────────────────────────────────────────────────────
@@ -182,7 +211,10 @@ export class WorktreeResolver {
       return;
     }
 
-    const basePath = this.s.originalBasePath || this.s.basePath;
+    // Resolve the project root for worktree operations via shared helper.
+    // Handles the case where originalBasePath is falsy and basePath is itself
+    // a worktree path — prevents double-nested worktree paths (#3729).
+    const basePath = resolveProjectRoot(this.s.originalBasePath, this.s.basePath);
     debugLog("WorktreeResolver", {
       action: "enterMilestone",
       milestoneId,
@@ -569,11 +601,13 @@ export class WorktreeResolver {
         }
       }
 
-      // Re-throw MergeConflictError so the auto loop can detect real code
-      // conflicts and stop instead of retrying forever (#2330).
-      if (err instanceof MergeConflictError) {
-        throw err;
-      }
+      // Restore state before re-throwing so callers always get a consistent
+      // session (#4380).
+      this.restoreToProjectRoot();
+      // Re-throw: MergeConflictError stops the auto loop (#2330); non-conflict
+      // errors (permission denied, filesystem failures) must also propagate so
+      // broken states are diagnosable (#4380).
+      throw err;
     }
 
     // Always restore basePath and rebuild — whether merge succeeded or failed
@@ -659,6 +693,8 @@ export class WorktreeResolver {
         error: msg,
       });
       ctx.notify(`Milestone merge failed (branch mode): ${msg}`, "warning");
+      // Re-throw all errors so callers can apply their own recovery logic (#4380).
+      throw err;
     }
   }
 
@@ -681,7 +717,16 @@ export class WorktreeResolver {
       currentMilestoneId,
       nextMilestoneId,
     });
-    this.mergeAndExit(currentMilestoneId, ctx);
+    try {
+      this.mergeAndExit(currentMilestoneId, ctx);
+    } catch (err) {
+      // mergeAndExit emits a warning and restores state when it fails during
+      // merge/cleanup. But if it throws before recovery runs (e.g., in
+      // validateMilestoneId or emitJournalEvent), basePath won't be restored
+      // to projectRoot — re-throw so we don't enter the next milestone with
+      // the current one unmerged.
+      if (this.s.basePath !== this.projectRoot) throw err;
+    }
     this.enterMilestone(nextMilestoneId, ctx);
   }
 }

package/src/resources/extensions/mcp-client/index.ts

@@ -514,7 +514,7 @@ export default function (pi: ExtensionAPI) {
 		await closeAll();
 	});
 
-	pi.on("session_switch", async () => {
+	pi.on("session_before_switch", async () => {
 		await closeAll();
 		configCache = null;
 	});

package/src/resources/extensions/ollama/index.ts

@@ -16,7 +16,8 @@
  * Respects OLLAMA_HOST env var for non-default endpoints.
  */
 
-import { importExtensionModule, type ExtensionAPI } from "@gsd/pi-coding-agent";
+import { type ExtensionAPI } from "@gsd/pi-coding-agent";
+import { importExtensionModule } from "@gsd/pi-coding-agent";
 import * as client from "./ollama-client.js";
 import { discoverModels } from "./ollama-discovery.js";
 import { registerOllamaCommands } from "./ollama-commands.js";
@@ -73,12 +74,11 @@ async function probeAndRegister(pi: ExtensionAPI): Promise<boolean> {
 	// so the "ollama" fallback is harmless. For cloud endpoints (OLLAMA_HOST pointing
 	// to ollama.com or a remote instance), OLLAMA_API_KEY is picked up here.
 	pi.registerProvider("ollama", {
-		authMode: "apiKey",
+		// authMode and isReady removed from ProviderConfig in pi 0.67.2
 		apiKey: process.env.OLLAMA_API_KEY ?? "ollama",
 		baseUrl,
 		api: "ollama-chat",
 		streamSimple: streamOllamaChat,
-		isReady: () => true,
 		models: models.map((m) => ({
 			id: m.id,
 			name: m.name,

package/src/resources/extensions/ollama/ollama-chat-provider.ts

@@ -14,7 +14,6 @@ import {
 	type AssistantMessageEventStream,
 	type Context,
 	type ImageContent,
-	type InferenceMetrics,
 	type Message,
 	type Model,
 	type SimpleStreamOptions,
@@ -168,7 +167,7 @@ export function streamOllamaChat(
 					endBlock();
 
 					output.usage = buildUsage(chunk);
-					output.inferenceMetrics = extractMetrics(chunk);
+					// inferenceMetrics removed from AssistantMessage in pi 0.67.2
 					// Preserve "toolUse" if tool calls were processed
 					if (output.stopReason !== "toolUse") {
 						output.stopReason = mapStopReason(chunk.done_reason);
@@ -194,7 +193,8 @@ function buildRequest(
 	context: Context,
 	options?: SimpleStreamOptions,
 ): OllamaChatRequest {
-	const ollamaOpts = (model.providerOptions ?? {}) as OllamaChatOptions;
+	// providerOptions removed from Model in pi 0.67.2; cast via unknown for extension data
+	const ollamaOpts = ((model as unknown as { providerOptions?: OllamaChatOptions }).providerOptions ?? {}) as OllamaChatOptions;
 
 	const request: OllamaChatRequest = {
 		model: model.id,
@@ -388,21 +388,9 @@ function buildUsage(chunk: OllamaChatResponse): Usage {
 	};
 }
 
-function extractMetrics(chunk: OllamaChatResponse): InferenceMetrics | undefined {
-	if (!chunk.eval_duration && !chunk.total_duration) return undefined;
-
-	const evalCount = chunk.eval_count ?? 0;
-	const evalDurationNs = chunk.eval_duration ?? 0;
-	const evalDurationMs = evalDurationNs / 1e6;
-	const tokensPerSecond = evalDurationNs > 0 ? evalCount / (evalDurationNs / 1e9) : 0;
-
-	return {
-		tokensPerSecond,
-		totalDurationMs: (chunk.total_duration ?? 0) / 1e6,
-		evalDurationMs,
-		promptEvalDurationMs: (chunk.prompt_eval_duration ?? 0) / 1e6,
-	};
-}
+// extractMetrics removed: InferenceMetrics was removed from pi-ai in pi 0.67.2
+// and inferenceMetrics was removed from AssistantMessage. Ollama perf metrics
+// (tokensPerSecond, evalDurationMs, etc.) are no longer surfaced via this path.
 
 // ─── Stream lifecycle helpers ───────────────────────────────────────────────
 // Replicated from openai-shared.ts (not exported from @gsd/pi-ai)

package/src/resources/extensions/remote-questions/config.ts

@@ -55,13 +55,24 @@ function hydrateRemoteTokensFromAuth(): void {
 
   try {
     const auth = AuthStorage.create();
+    const authData = (auth as unknown as {
+      data?: Record<string, { type?: string; key?: string } | Array<{ type?: string; key?: string }>>;
+    }).data ?? {};
 
     for (const [providerId, envVar] of needed) {
       try {
-        const creds = auth.getCredentialsForProvider(providerId);
-        const apiKeyCred = creds.find((c: { type: string; key?: string }) => c.type === "api_key" && !!c.key) as
-          | { type: "api_key"; key: string }
-          | undefined;
+        const raw = authData[providerId];
+        const creds = Array.isArray(raw)
+          ? raw
+          : raw
+            ? [raw]
+            : [];
+        if (creds.length === 0) {
+          const fallbackCred = auth.get(providerId) as { type?: string; key?: string } | undefined;
+          if (fallbackCred) creds.push(fallbackCred);
+        }
+
+        const apiKeyCred = creds.find((c) => c.type === "api_key" && !!c.key);
         if (apiKeyCred?.key) {
           process.env[envVar] = apiKeyCred.key;
         }

package/src/resources/extensions/search-the-web/command-search-provider.ts

@@ -8,7 +8,7 @@
  * All provider logic lives in provider.ts (S01) — this is pure UI wiring.
  */
 
-import { isAnthropicApi } from '@gsd/pi-ai'
+import { supportsNativeWebSearch } from './native-search.js'
 import type { ExtensionAPI } from '@gsd/pi-coding-agent'
 import type { AutocompleteItem } from '@gsd/pi-tui'
 import {
@@ -91,9 +91,10 @@ export function registerSearchProviderCommand(pi: ExtensionAPI): void {
 
       setSearchProviderPreference(chosen)
       const effective = resolveSearchProvider()
-      // Gate on api (#4478 / ADR-012): covers claude-code, anthropic-vertex, and
-      // other Anthropic-fronting transports — not just the plain `anthropic` provider.
-      const isAnthropic = isAnthropicApi(ctx.model)
+      // Gate on api shape + provider allowlist: the info note must match the
+      // actual runtime behavior in native-search.ts. Claude served via copilot
+      // / minimax / kimi is anthropic-shaped but does NOT run native search.
+      const isAnthropic = supportsNativeWebSearch(ctx.model)
       const nativeNote = isAnthropic ? '\nNote: Native Anthropic web search is also active (automatic, no API key needed).' : ''
       ctx.ui.notify(
         `Search provider set to ${chosen}. Effective provider: ${effective ?? 'none (no API keys)'}${nativeNote}`,

package/src/resources/extensions/search-the-web/index.ts

@@ -5,7 +5,8 @@
  * interactive mode so startup is not blocked on the full search tool stack.
  */
 
-import { importExtensionModule, type ExtensionAPI } from "@gsd/pi-coding-agent";
+import { type ExtensionAPI } from "@gsd/pi-coding-agent";
+import { importExtensionModule } from "@gsd/pi-coding-agent";
 import { registerSearchProviderCommand } from "./command-search-provider.js";
 import { registerNativeSearchHooks } from "./native-search.js";
 

package/src/resources/extensions/search-the-web/native-search.ts

@@ -17,6 +17,41 @@ export const CUSTOM_SEARCH_TOOL_NAMES = ["search-the-web", "search_and_read", "g
 /** Thinking block types that require signature validation by the API */
 const THINKING_TYPES = new Set(["thinking", "redacted_thinking"]);
 
+/**
+ * Providers whose Anthropic-Messages endpoint is known to accept the native
+ * `web_search_20250305` server tool. Anthropic-shaped transports NOT in this
+ * set (github-copilot, minimax, kimi-coding, opencode, vercel-ai-gateway,
+ * etc.) route Claude or Claude-compatible models through the Messages API
+ * but do NOT expose the server-side search tool — injecting it yields a
+ * 400 "unsupported_value" from their endpoints (regression from #4492).
+ *
+ * Keep this allowlist tight — err on the side of custom/Brave search rather
+ * than a runtime 400. Add a provider here only after confirming its endpoint
+ * accepts the tool type.
+ */
+const NATIVE_WEB_SEARCH_PROVIDERS = new Set([
+  "anthropic",
+  "claude-code",
+  "anthropic-vertex",
+  "vercel-ai-gateway",
+]);
+
+/**
+ * True when the model is an Anthropic-shaped transport AND the provider is
+ * known to accept the native `web_search_20250305` tool. Gate both on api
+ * shape (#4478 / ADR-012) and on provider identity (#444 regression guard
+ * and #4492 scope correction) — provider-level discrimination is legitimate
+ * per ADR-012 for credential/behavior differences that api shape can't
+ * express.
+ */
+export function supportsNativeWebSearch(
+  model: { api?: string; provider?: string } | null | undefined
+): boolean {
+  if (!isAnthropicApi(model)) return false;
+  const provider = model?.provider;
+  return typeof provider === "string" && NATIVE_WEB_SEARCH_PROVIDERS.has(provider);
+}
+
 /**
  * Maximum number of native web searches allowed per session (agent unit).
  * The Anthropic API's `max_uses` is per-request — it resets on each API call.
@@ -95,10 +130,11 @@ export function registerNativeSearchHooks(pi: NativeSearchPI): { getIsAnthropic:
   pi.on("model_select", async (event: any, ctx: any) => {
     modelSelectFired = true;
     const wasAnthropic = isAnthropicProvider;
-    // Gate on `api` not `provider` (#4478 / ADR-012): covers claude-code OAuth,
-    // anthropic-vertex, and Vercel-gateway-hosted Anthropic — all serve the
-    // Messages API and accept the native web_search tool.
-    isAnthropicProvider = isAnthropicApi(event.model);
+    // Gate on api shape AND provider allowlist: direct Anthropic, claude-code
+    // OAuth, and anthropic-vertex accept `web_search_20250305`; copilot /
+    // minimax / kimi / opencode route Claude-compat models through the same
+    // wire protocol but reject the server-side tool (#4492 regression).
+    isAnthropicProvider = supportsNativeWebSearch(event.model);
 
     const hasBrave = !!process.env.BRAVE_API_KEY;
 
@@ -145,17 +181,17 @@ export function registerNativeSearchHooks(pi: NativeSearchPI): { getIsAnthropic:
     // modelsAreEqual suppresses model_select AND the SDK doesn't pass model.
     const eventModel = event.model as { provider?: string; api?: string } | undefined;
     let isAnthropic: boolean;
-    if (eventModel?.api) {
-      // Preferred path: gate on wire protocol (#4478 / ADR-012).
-      isAnthropic = isAnthropicApi(eventModel);
-    } else if (eventModel?.provider) {
-      // Fallback for event shapes that carry provider but not api — only plain
-      // `anthropic` maps unambiguously without the api field. Other Anthropic
-      // transports will arrive via the modelSelectFired or model-name branch.
-      isAnthropic = eventModel.provider === "anthropic";
+    if (eventModel?.api || eventModel?.provider) {
+      // Preferred path: gate on api shape + provider allowlist. Both fields
+      // are authoritative when present — do NOT fall back to the model-name
+      // heuristic, which would misclassify copilot-served Claude as Anthropic
+      // (#444 regression) or minimax-served Claude-compat as Anthropic (#4492).
+      isAnthropic = supportsNativeWebSearch(eventModel);
     } else if (modelSelectFired) {
       isAnthropic = isAnthropicProvider;
     } else {
+      // Last resort: session-restore paths where the SDK doesn't pass model.
+      // The model-name prefix is best-effort and assumes direct Anthropic.
       const modelName = typeof payload.model === "string" ? payload.model : "";
       isAnthropic = modelName.startsWith("claude-");
     }

package/src/resources/extensions/shared/tests/format-utils.test.ts

@@ -11,6 +11,7 @@ import {
   centerLine,
   fitColumns,
 } from "../layout-utils.js";
+import { visibleWidth } from "@gsd/pi-tui";
 
 describe("formatDuration", () => {
   it("formats seconds", () => {
@@ -59,8 +60,8 @@ describe("joinColumns", () => {
 
   it("truncates when content overflows", () => {
     const result = joinColumns("a".repeat(20), "b".repeat(20), 30);
-    // Should be truncated to 30 chars
-    assert.ok(result.length <= 30);
+    // Should be truncated to 30 visible columns (ANSI reset codes may make string length > 30)
+    assert.ok(visibleWidth(result) <= 30);
   });
 });
 
@@ -72,7 +73,8 @@ describe("centerLine", () => {
 
   it("truncates when content exceeds width", () => {
     const result = centerLine("abcdefgh", 4);
-    assert.ok(result.length <= 4);
+    // Should be truncated to 4 visible columns (ANSI reset codes may make string length > 4)
+    assert.ok(visibleWidth(result) <= 4);
   });
 });
 

package/src/resources/extensions/universal-config/index.ts

@@ -114,7 +114,7 @@ export default function universalConfig(pi: ExtensionAPI) {
 
   // ── Invalidate cache on session switch ──────────────────────────────────
 
-  pi.on("session_switch", () => {
+  pi.on("session_before_switch", () => {
     cachedResult = null;
   });
 }

package/src/resources/skills/api-design/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: api-design
+description: Design or review an HTTP/REST/GraphQL API for versioning, pagination, error shapes, idempotency, auth, and evolvability. Use when asked to "design an API", "shape the endpoints", "design the schema", "add a new endpoint", "review this API", or when building/modifying a public or internal HTTP surface. Complements `design-an-interface` (which is interface-agnostic) by covering HTTP-specific concerns like status codes, cache headers, and breaking-change management.
+---
+
+<objective>
+Shape an HTTP or GraphQL API so callers get predictable, evolvable, and honest semantics. The deliverable is a concrete endpoint/schema sketch with: URL or operation names, method/verb, request shape, response shape, error shape, auth model, pagination strategy, and versioning stance. Optimize for "clients that exist in 2 years" over "client that's easy to write today".
+</objective>
+
+<context>
+GSD-2 has `design-an-interface` for general module-interface design; this skill is the HTTP/GraphQL specialization. REST and GraphQL carry baggage — status codes, verbs, nullability, pagination — that a generic interface-design discussion glosses over.
+
+Invocation points:
+- Adding a new public API endpoint
+- Redesigning an internal API boundary between services
+- Code review of a PR that introduces HTTP handlers
+- A slice whose acceptance criteria include "the API works"
+- A GraphQL schema change
+</context>
+
+<core_principle>
+**CALLERS OUTLIVE YOUR ASSUMPTIONS.** An API you ship today has to keep working when your internals change, when the mobile app version two is still in use, and when a third party integrates against it. Design for extension, not just for the current caller.
+
+**HONEST STATUS CODES.** 200 OK with `{"error": "not found"}` is a lie. 404 says not found. Use the HTTP semantics the protocol offers — HTTP clients, caches, and intermediaries rely on them.
+
+**PAGINATION IS NON-OPTIONAL.** Any list endpoint that doesn't paginate will eventually get a request for "all records" that kills your database.
+</core_principle>
+
+<process>
+
+## Step 1: Gather the contract
+
+Answer, or ask (one round, 1–3 questions):
+
+1. **Who are the callers?** Internal service / mobile app / public third-party / same-repo frontend.
+2. **What's the versioning stance?** None / URL-path (`/v1/`) / header-based / GraphQL schema evolution.
+3. **Auth model?** Public / API key / OAuth / session cookie / mTLS / none-but-internal-only.
+4. **Idempotency expectation?** Is a retry safe? Required?
+5. **Consistency model?** Read-your-writes, eventual, serializable?
+
+## Step 2: Resource and operation naming
+
+### REST
+
+- Nouns not verbs in URLs: `POST /users`, not `POST /createUser`.
+- Plural resources: `/users/42`, not `/user/42`.
+- Nested only when the relationship is hierarchical and the child has no independent identity: `/users/42/sessions/3`. Otherwise flat: `/sessions/3?userId=42`.
+- Use subresources for actions that don't fit CRUD: `POST /users/42:deactivate` (colon syntax) or `POST /users/42/actions/deactivate`.
+
+### GraphQL
+
+- Queries are nouns; mutations are verbs: `user(id)`, `createUser(input)`, `deactivateUser(id)`.
+- Group related mutations under an input type: `createUser(input: CreateUserInput!)`.
+- Return the affected object plus any derived/computed fields from mutations — lets clients avoid a refetch.
+
+## Step 3: Methods and status codes
+
+### REST
+
+| Method | Intent | Idempotent? | Default success |
+|---|---|---|---|
+| GET | Read | Yes | 200, or 304 if conditional |
+| POST | Create or non-idempotent action | No | 201 with `Location` on create, 200 on action |
+| PUT | Replace (full-object) | Yes | 200 with body, or 204 |
+| PATCH | Partial update | No (usually) | 200 with body |
+| DELETE | Remove | Yes | 204 |
+
+Errors:
+- 400: caller screwed up the request shape
+- 401: no/invalid auth
+- 403: authed but not allowed
+- 404: resource doesn't exist
+- 409: conflict (version mismatch, unique constraint)
+- 410: gone (vs 404 when the resource previously existed and you want to signal that)
+- 422: validation failed
+- 429: rate-limited — include `Retry-After`
+- 500: genuinely unexpected server error
+- 503: service down or overloaded — include `Retry-After`
+
+Never 200-with-error-body. Never 500 for a 4xx cause.
+
+### GraphQL
+
+- Top-level errors (`errors[]`) for transport-level failures. Domain errors (validation, not-found, forbidden) go in the typed return — use a union or result type.
+- Partial results are expected; design the schema so `null` on a field is meaningful, not a signal of generic failure.
+
+## Step 4: Pagination
+
+- **Cursor-based by default.** Opaque cursor string, `limit`, return `nextCursor` when more exists. Scales, stable under writes.
+- **Offset-based only when:** dataset is small, user needs jump-to-page semantics (admin tables), and you're willing to accept stability drift.
+- **Never "return everything"** as default. Put a hard upper bound on `limit` (e.g., 200).
+- GraphQL: use Relay-style connections (`edges`, `pageInfo`) if the ecosystem expects it; otherwise a simpler `{items, nextCursor}` is fine.
+
+## Step 5: Error shape
+
+Standardize one shape and use it everywhere. Example REST:
+
+```json
+{
+  "error": {
+    "code": "user_not_found",
+    "message": "No user with id 42",
+    "details": { "userId": 42 },
+    "requestId": "req_abc123"
+  }
+}
+```
+
+- `code` is machine-readable; stable; documented.
+- `message` is human-readable; can change.
+- `details` carries structured context.
+- `requestId` lets callers report bugs.
+
+Errors don't leak stack traces, file paths, or internal queries.
+
+## Step 6: Idempotency, caching, concurrency
+
+- **Idempotency keys** for POST operations that mustn't double-execute on retry. Caller passes `Idempotency-Key: <uuid>`; server dedupes for a window.
+- **ETags** for GET + conditional updates (`If-Match` on PUT/PATCH).
+- **Cache-Control** on GETs that are safely cacheable.
+- **Optimistic concurrency:** when multiple writers collide, 409 with the current state. Don't silently clobber.
+
+## Step 7: Versioning and evolution
+
+- **Additive changes are free:** new optional fields, new endpoints, new optional query params.
+- **Breaking changes need a plan:** path-versioned (`/v2/`), sunset headers on `/v1/`, deprecation window communicated. Or, for GraphQL, `@deprecated` on fields with a migration note.
+- **Document the contract:** OpenAPI/GraphQL SDL. Keep it in the repo. Make it part of the PR that introduces the change.
+
+## Step 8: Review or write it up
+
+If this is a review, produce findings in the same shape as `security-review` / `review` — file:line, category, recommendation.
+
+If this is a new design, produce:
+
+```markdown
+## <API name>
+
+### Scope
+<what the API is for, who calls it>
+
+### Endpoints / Operations
+- `POST /users` — create user. Request: `{email, name}`. Response 201: `{id, email, name, createdAt}` + `Location: /users/<id>`. Errors: 409 email taken, 422 invalid.
+- ...
+
+### Auth
+<model + where to put the credential>
+
+### Pagination
+<cursor shape, max limit>
+
+### Error shape
+<one canonical shape>
+
+### Idempotency / concurrency
+<rules>
+
+### Versioning
+<stance + how breaking changes will be handled>
+
+### OpenAPI / SDL
+<link or inline>
+```
+
+Append architectural decisions to `.gsd/DECISIONS.md`.
+
+</process>
+
+<anti_patterns>
+
+- **200 OK with `{"error": "..."}`.** Lies to caches, proxies, retry libraries.
+- **Unbounded list endpoints.** `GET /users` without a `limit` cap will bite you.
+- **Offset pagination at scale.** Drifts under writes; slow at high offsets.
+- **Free-form error messages with no code.** Machine callers can't branch on prose.
+- **Breaking changes in-place.** Callers break; versioning exists for a reason.
+- **Ignoring idempotency on retriable POSTs.** Double-charges, duplicate records.
+- **Auth checks at the handler only, not the service layer.** Defense in depth.
+
+</anti_patterns>
+
+<success_criteria>
+
+- [ ] Every endpoint/operation has named request, response, and error shapes.
+- [ ] Status codes match HTTP semantics — no 200-with-error.
+- [ ] List endpoints paginate; max limit is documented.
+- [ ] A single error shape is used everywhere, with a machine-readable code.
+- [ ] Versioning stance is stated — even if the answer is "additive only for now."
+- [ ] OpenAPI/SDL reflects the design and lives in the repo.
+- [ ] Decisions appear in `.gsd/DECISIONS.md`.
+
+</success_criteria>