gsd-pi 2.75.0 → 2.76.0-dev.4100bd590

package/src/resources/extensions/shared/rtk-shared.ts

@@ -0,0 +1,58 @@
+import { existsSync } from "node:fs";
+import { homedir as osHomedir } from "node:os";
+import { delimiter, join } from "node:path";
+
+export const GSD_RTK_DISABLED_ENV = "GSD_RTK_DISABLED";
+export const GSD_RTK_PATH_ENV = "GSD_RTK_PATH";
+export const RTK_TELEMETRY_DISABLED_ENV = "RTK_TELEMETRY_DISABLED";
+
+export function isTruthy(value: string | undefined): boolean {
+  if (!value) return false;
+  const normalized = value.trim().toLowerCase();
+  return normalized === "1" || normalized === "true" || normalized === "yes";
+}
+
+export function isRtkEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return !isTruthy(env[GSD_RTK_DISABLED_ENV]);
+}
+
+export function getManagedRtkDir(env: NodeJS.ProcessEnv = process.env): string {
+  return join(env.GSD_HOME || join(osHomedir(), ".gsd"), "agent", "bin");
+}
+
+export function getRtkBinaryName(platform: NodeJS.Platform = process.platform): string {
+  return platform === "win32" ? "rtk.exe" : "rtk";
+}
+
+export function getPathValue(env: NodeJS.ProcessEnv): string | undefined {
+  const pathKey = Object.keys(env).find((key) => key.toLowerCase() === "path");
+  return pathKey ? env[pathKey] : env.PATH;
+}
+
+export function resolvePathCandidates(pathValue: string | undefined): string[] {
+  if (!pathValue) return [];
+  return pathValue
+    .split(delimiter)
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+export function resolveSystemRtkPath(
+  pathValue: string | undefined,
+  platform: NodeJS.Platform = process.platform,
+): string | null {
+  const candidates = platform === "win32"
+    ? ["rtk.exe", "rtk.cmd", "rtk.bat", "rtk"]
+    : ["rtk"];
+
+  for (const dir of resolvePathCandidates(pathValue)) {
+    for (const candidate of candidates) {
+      const fullPath = join(dir, candidate);
+      if (existsSync(fullPath)) {
+        return fullPath;
+      }
+    }
+  }
+
+  return null;
+}

package/src/resources/extensions/shared/rtk.ts

@@ -1,19 +1,21 @@
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
-import { homedir } from "node:os";
-import { delimiter, join } from "node:path";
+import { join } from "node:path";
+import {
+  GSD_RTK_DISABLED_ENV,
+  GSD_RTK_PATH_ENV,
+  RTK_TELEMETRY_DISABLED_ENV,
+  getManagedRtkDir,
+  getPathValue,
+  getRtkBinaryName,
+  isRtkEnabled,
+  resolveSystemRtkPath,
+} from "./rtk-shared.js";
 
-const GSD_RTK_PATH_ENV = "GSD_RTK_PATH";
-const GSD_RTK_DISABLED_ENV = "GSD_RTK_DISABLED";
 const GSD_RTK_REWRITE_TIMEOUT_MS_ENV = "GSD_RTK_REWRITE_TIMEOUT_MS";
-const RTK_TELEMETRY_DISABLED_ENV = "RTK_TELEMETRY_DISABLED";
 const RTK_REWRITE_TIMEOUT_MS = 5_000;
 
-function isTruthy(value: string | undefined): boolean {
-  if (!value) return false;
-  const normalized = value.trim().toLowerCase();
-  return normalized === "1" || normalized === "true" || normalized === "yes";
-}
+export { isRtkEnabled };
 
 function getRewriteTimeoutMs(env: NodeJS.ProcessEnv = process.env): number {
   const configured = Number.parseInt(env[GSD_RTK_REWRITE_TIMEOUT_MS_ENV] ?? "", 10);
@@ -23,10 +25,6 @@ function getRewriteTimeoutMs(env: NodeJS.ProcessEnv = process.env): number {
   return RTK_REWRITE_TIMEOUT_MS;
 }
 
-export function isRtkEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
-  return !isTruthy(env[GSD_RTK_DISABLED_ENV]);
-}
-
 export function buildRtkEnv(env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
   return {
     ...env,
@@ -34,44 +32,6 @@ export function buildRtkEnv(env: NodeJS.ProcessEnv = process.env): NodeJS.Proces
   };
 }
 
-function getManagedRtkDir(env: NodeJS.ProcessEnv = process.env): string {
-  return join(env.GSD_HOME || join(homedir(), ".gsd"), "agent", "bin");
-}
-
-function getRtkBinaryName(platform: NodeJS.Platform = process.platform): string {
-  return platform === "win32" ? "rtk.exe" : "rtk";
-}
-
-function getPathValue(env: NodeJS.ProcessEnv): string | undefined {
-  const pathKey = Object.keys(env).find((key) => key.toLowerCase() === "path");
-  return pathKey ? env[pathKey] : env.PATH;
-}
-
-function resolvePathCandidates(pathValue: string | undefined): string[] {
-  if (!pathValue) return [];
-  return pathValue
-    .split(delimiter)
-    .map((part) => part.trim())
-    .filter(Boolean);
-}
-
-function resolveSystemRtkPath(pathValue: string | undefined, platform: NodeJS.Platform = process.platform): string | null {
-  const candidates = platform === "win32"
-    ? ["rtk.exe", "rtk.cmd", "rtk.bat", "rtk"]
-    : ["rtk"];
-
-  for (const dir of resolvePathCandidates(pathValue)) {
-    for (const candidate of candidates) {
-      const fullPath = join(dir, candidate);
-      if (existsSync(fullPath)) {
-        return fullPath;
-      }
-    }
-  }
-
-  return null;
-}
-
 export interface ResolveRtkBinaryPathOptions {
   binaryPath?: string;
   env?: NodeJS.ProcessEnv;

package/src/resources/extensions/shared/tests/interview-preview.test.ts

@@ -0,0 +1,177 @@
+import { describe, it, before } from "node:test";
+import assert from "node:assert/strict";
+import { Markdown, visibleWidth } from "@gsd/pi-tui";
+import { getMarkdownTheme, initTheme } from "@gsd/pi-coding-agent";
+import type { QuestionOption, Question } from "../interview-ui.js";
+
+// Theme must be initialized before Markdown rendering
+before(() => { initTheme(); });
+
+// ─── QuestionOption.preview type contract ─────────────────────────────────────
+
+describe("QuestionOption preview field", () => {
+  it("accepts option without preview (backward compat)", () => {
+    const opt: QuestionOption = { label: "A", description: "Desc A" };
+    assert.equal(opt.preview, undefined);
+  });
+
+  it("accepts option with preview string", () => {
+    const opt: QuestionOption = {
+      label: "A",
+      description: "Desc A",
+      preview: "## Code\n```ts\nconst x = 1;\n```",
+    };
+    assert.equal(typeof opt.preview, "string");
+    assert.ok(opt.preview!.length > 0);
+  });
+
+  it("Question with mixed preview/no-preview options is valid", () => {
+    const q: Question = {
+      id: "test",
+      header: "Test",
+      question: "Pick one",
+      options: [
+        { label: "A", description: "Has preview", preview: "# Preview A" },
+        { label: "B", description: "No preview" },
+        { label: "C", description: "Has preview", preview: "# Preview C" },
+      ],
+    };
+    const withPreview = q.options.filter((o) => o.preview);
+    const withoutPreview = q.options.filter((o) => !o.preview);
+    assert.equal(withPreview.length, 2);
+    assert.equal(withoutPreview.length, 1);
+  });
+});
+
+// ─── Markdown preview rendering ───────────────────────────────────────────────
+
+describe("preview column rendering", () => {
+  it("Markdown component renders non-empty output for a markdown string", () => {
+    const mdTheme = getMarkdownTheme();
+    const md = new Markdown("## Hello\n\nSome **bold** text.", 1, 0, mdTheme);
+    const lines = md.render(40);
+    assert.ok(lines.length > 0, "Markdown should produce at least one line");
+    // At least one line should have visible content
+    const hasContent = lines.some((l) => visibleWidth(l) > 0);
+    assert.ok(hasContent, "At least one rendered line should have visible content");
+  });
+
+  it("Markdown component renders code blocks", () => {
+    const mdTheme = getMarkdownTheme();
+    const md = new Markdown("```ts\nconst x = 1;\n```", 1, 0, mdTheme);
+    const lines = md.render(40);
+    assert.ok(lines.length > 0);
+    const joined = lines.join("\n");
+    // The rendered output should contain the code content somewhere
+    assert.ok(joined.includes("const") || joined.includes("x"), "Code block content should be present");
+  });
+
+  it("Markdown component respects width constraint", () => {
+    const mdTheme = getMarkdownTheme();
+    const longContent = "This is a very long paragraph that should wrap when rendered at a narrow width constraint.";
+    const md = new Markdown(longContent, 1, 0, mdTheme);
+    const lines = md.render(30);
+    // All lines should respect the width
+    for (const line of lines) {
+      assert.ok(
+        visibleWidth(line) <= 30,
+        `Line exceeds width: "${line}" (visible: ${visibleWidth(line)})`,
+      );
+    }
+  });
+});
+
+// ─── Layout stability ─────────────────────────────────────────────────────────
+
+describe("layout stability", () => {
+  const MIN_PREVIEW_WIDTH = 30;
+  const MIN_OPTIONS_WIDTH = 30;
+  const DIVIDER_WIDTH = 3;
+
+  /** Mirrors questionHasAnyPreview() logic from interview-ui.ts */
+  function questionHasAnyPreview(options: QuestionOption[]): boolean {
+    return options.some((o) => o.preview != null && o.preview.trim().length > 0);
+  }
+
+  it("useSideBySide is true when ANY option has a preview (not just current)", () => {
+    const options: QuestionOption[] = [
+      { label: "A", description: "Has preview", preview: "# Hello" },
+      { label: "B", description: "No preview" },
+      { label: "C", description: "Also no preview" },
+    ];
+    const width = 100;
+    const useSideBySide = questionHasAnyPreview(options) && width >= (MIN_OPTIONS_WIDTH + MIN_PREVIEW_WIDTH + DIVIDER_WIDTH);
+    assert.equal(useSideBySide, true, "side-by-side should activate when any option has preview");
+  });
+
+  it("useSideBySide is false when no options have a preview", () => {
+    const options: QuestionOption[] = [
+      { label: "A", description: "No preview" },
+      { label: "B", description: "No preview" },
+    ];
+    const useSideBySide = questionHasAnyPreview(options) && 100 >= 63;
+    assert.equal(useSideBySide, false);
+  });
+
+  it("PREVIEW_MAX_LINES produces constant side-by-side height", () => {
+    const PREVIEW_MAX_LINES = 20;
+    // Short and long content both produce exactly PREVIEW_MAX_LINES after cap+pad
+    for (const contentLen of [3, 10, 15, 30]) {
+      const capped = Math.min(contentLen, PREVIEW_MAX_LINES);
+      const padded = Math.max(capped, PREVIEW_MAX_LINES);
+      assert.equal(padded, PREVIEW_MAX_LINES, `content ${contentLen} should pad to ${PREVIEW_MAX_LINES}`);
+    }
+  });
+
+  it("total with PREVIEW_MAX_LINES fits in standard terminal (single-question)", () => {
+    const PREVIEW_MAX_LINES = 20;
+    const singleHeader = 1;  // bar only
+    const footer = 3;        // blank + hints + bar
+    const total = singleHeader + PREVIEW_MAX_LINES + footer;
+    assert.ok(total <= 24, `single-question total ${total} exceeds 24-row terminal`);
+  });
+});
+
+// ─── Preview layout constants ─────────────────────────────────────────────────
+
+describe("preview layout constraints", () => {
+  const MIN_PREVIEW_WIDTH = 30;
+  const MIN_OPTIONS_WIDTH = 30;
+  const DIVIDER_WIDTH = 3;
+  const PREVIEW_RATIO = 0.60;
+
+  it("minimum terminal width for preview = MIN_OPTIONS + MIN_PREVIEW + DIVIDER", () => {
+    const minWidth = MIN_OPTIONS_WIDTH + MIN_PREVIEW_WIDTH + DIVIDER_WIDTH;
+    assert.equal(minWidth, 63);
+  });
+
+  it("at minimum width, both columns get their floor", () => {
+    const width = 63;
+    const previewWidth = Math.max(MIN_PREVIEW_WIDTH, Math.floor(width * PREVIEW_RATIO));
+    const leftWidth = Math.max(MIN_OPTIONS_WIDTH, width - previewWidth - DIVIDER_WIDTH);
+    assert.ok(previewWidth >= MIN_PREVIEW_WIDTH, `preview ${previewWidth} < min ${MIN_PREVIEW_WIDTH}`);
+    assert.ok(leftWidth >= MIN_OPTIONS_WIDTH, `options ${leftWidth} < min ${MIN_OPTIONS_WIDTH}`);
+  });
+
+  it("at wide terminal, preview ratio is approximately 60%", () => {
+    const width = 120;
+    const previewWidth = Math.max(MIN_PREVIEW_WIDTH, Math.floor(width * PREVIEW_RATIO));
+    const leftWidth = Math.max(MIN_OPTIONS_WIDTH, width - previewWidth - DIVIDER_WIDTH);
+    // Preview should be close to 60% of total
+    const actualRatio = previewWidth / width;
+    assert.ok(actualRatio >= 0.55 && actualRatio <= 0.65, `Ratio ${actualRatio} not near 0.60`);
+    assert.ok(leftWidth >= MIN_OPTIONS_WIDTH);
+  });
+
+  it("preview disabled when terminal is too narrow", () => {
+    const width = 62; // just under threshold
+    const canShow = width >= (MIN_OPTIONS_WIDTH + MIN_PREVIEW_WIDTH + DIVIDER_WIDTH);
+    assert.equal(canShow, false);
+  });
+
+  it("preview enabled when terminal is exactly at threshold", () => {
+    const width = 63;
+    const canShow = width >= (MIN_OPTIONS_WIDTH + MIN_PREVIEW_WIDTH + DIVIDER_WIDTH);
+    assert.equal(canShow, true);
+  });
+});

package/src/resources/extensions/shared/tests/preview-layout.test.ts

@@ -0,0 +1,120 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { visibleWidth } from "@gsd/pi-tui";
+import { mergeSideBySide, padRight } from "../layout-utils.js";
+
+// ─── mergeSideBySide ──────────────────────────────────────────────────────────
+
+describe("mergeSideBySide", () => {
+  const plainDivider = " | ";
+
+  it("merges equal-length line arrays", () => {
+    const left = ["aaa", "bbb"];
+    const right = ["111", "222"];
+    const merged = mergeSideBySide(left, right, 6, plainDivider, 80);
+    assert.equal(merged.length, 2);
+    // left padded to 6, then divider, then right
+    assert.ok(merged[0].includes("aaa"));
+    assert.ok(merged[0].includes("111"));
+    assert.ok(merged[1].includes("bbb"));
+    assert.ok(merged[1].includes("222"));
+  });
+
+  it("pads short left lines to leftWidth", () => {
+    const left = ["ab"];
+    const right = ["xy"];
+    const merged = mergeSideBySide(left, right, 6, plainDivider, 80);
+    // "ab" padded to 6 = "ab    ", then " | ", then "xy"
+    assert.ok(merged[0].startsWith("ab    "));
+  });
+
+  it("handles empty left array", () => {
+    const merged = mergeSideBySide([], ["aaa", "bbb"], 6, plainDivider, 80);
+    assert.equal(merged.length, 2);
+    // Left side should be blank (just padding)
+    assert.ok(merged[0].startsWith("      "));
+  });
+
+  it("handles empty right array", () => {
+    const merged = mergeSideBySide(["aaa", "bbb"], [], 6, plainDivider, 80);
+    assert.equal(merged.length, 2);
+    assert.ok(merged[0].includes("aaa"));
+  });
+
+  it("handles both arrays empty", () => {
+    const merged = mergeSideBySide([], [], 6, plainDivider, 80);
+    assert.equal(merged.length, 0);
+  });
+
+  it("handles mismatched lengths — left longer", () => {
+    const left = ["a", "b", "c"];
+    const right = ["1"];
+    const merged = mergeSideBySide(left, right, 6, plainDivider, 80);
+    assert.equal(merged.length, 3);
+    assert.ok(merged[0].includes("1"));
+    // Lines 2 and 3 have empty right side
+    assert.ok(merged[2].includes("c"));
+  });
+
+  it("handles mismatched lengths — right longer", () => {
+    const left = ["a"];
+    const right = ["1", "2", "3"];
+    const merged = mergeSideBySide(left, right, 6, plainDivider, 80);
+    assert.equal(merged.length, 3);
+    assert.ok(merged[2].includes("3"));
+  });
+
+  it("truncates merged output to totalWidth", () => {
+    const left = ["aaaaaaaaaa"];  // 10 chars
+    const right = ["bbbbbbbbbb"]; // 10 chars
+    const merged = mergeSideBySide(left, right, 10, plainDivider, 15);
+    // Should be truncated to 15 visible chars
+    assert.ok(visibleWidth(merged[0]) <= 15);
+  });
+
+  it("handles ANSI-colored left content correctly", () => {
+    const red = "\x1b[31m";
+    const reset = "\x1b[0m";
+    const left = [`${red}hello${reset}`]; // visible: "hello" (5 chars)
+    const right = ["world"];
+    const merged = mergeSideBySide(left, right, 8, plainDivider, 80);
+    // "hello" is 5 visible chars, padded to 8 = 3 spaces of padding
+    // The ANSI codes don't count toward visible width
+    assert.ok(merged[0].includes(red));
+    assert.ok(merged[0].includes("world"));
+    // Verify padding is correct (8 visible chars on left side)
+    const beforeDivider = merged[0].split(" | ")[0];
+    assert.equal(visibleWidth(beforeDivider), 8);
+  });
+
+  it("handles ANSI-colored divider", () => {
+    const dim = "\x1b[2m";
+    const reset = "\x1b[0m";
+    const styledDivider = `${dim} │ ${reset}`;
+    const left = ["abc"];
+    const right = ["xyz"];
+    const merged = mergeSideBySide(left, right, 6, styledDivider, 80);
+    assert.equal(merged.length, 1);
+    assert.ok(merged[0].includes("abc"));
+    assert.ok(merged[0].includes("xyz"));
+  });
+});
+
+// ─── padRight with ANSI ───────────────────────────────────────────────────────
+
+describe("padRight with ANSI content", () => {
+  it("pads based on visible width, not string length", () => {
+    const red = "\x1b[31m";
+    const reset = "\x1b[0m";
+    const colored = `${red}hi${reset}`;
+    // colored.length >> 2, but visible width is 2
+    const padded = padRight(colored, 6);
+    assert.equal(visibleWidth(padded), 6);
+  });
+
+  it("does not over-pad plain text", () => {
+    const padded = padRight("hello", 5);
+    assert.equal(padded, "hello");
+    assert.equal(visibleWidth(padded), 5);
+  });
+});

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>