wicked-garden 12.27.0

package/skills/engineering/integration/refs/versioning-migration-strategies.md

@@ -0,0 +1,257 @@
+---
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+# API Versioning Guide: Migration Strategies
+
+## Migration Strategies
+
+### Dual-Write Pattern
+
+Support multiple versions simultaneously.
+
+```typescript
+class UserService {
+  async createUser(data: any, version: string): Promise<User> {
+    const user = await db.users.create(data);
+
+    // Write to both old and new formats
+    if (version === '1') {
+      return this.formatV1(user);
+    } else if (version === '2') {
+      return this.formatV2(user);
+    }
+  }
+
+  private formatV1(user: User) {
+    return {
+      id: user.id,
+      name: user.name
+    };
+  }
+
+  private formatV2(user: User) {
+    return {
+      id: user.id,
+      name: user.name,
+      email: user.email,
+      created_at: user.createdAt
+    };
+  }
+}
+```
+
+### Adapter Pattern
+
+Transform between versions.
+
+```typescript
+class V1toV2Adapter {
+  transform(v1Response: any): any {
+    return {
+      ...v1Response,
+      email: v1Response.user_email,  // Renamed field
+      createdAt: v1Response.created_date,  // Renamed field
+      metadata: {
+        // Restructured
+        version: '2.0',
+        legacy: true
+      }
+    };
+  }
+}
+
+// Usage
+app.get('/api/v2/users/:id', async (req, res) => {
+  const user = await userServiceV1.getUser(req.params.id);
+  const adapted = new V1toV2Adapter().transform(user);
+  res.json(adapted);
+});
+```
+
+### Proxy Pattern
+
+V2 proxies to V1 with transformations.
+
+```typescript
+// V2 endpoint delegates to V1
+app.get('/api/v2/users/:id', async (req, res) => {
+  // Call V1 handler
+  const v1Response = await handleV1Request(req);
+
+  // Transform to V2 format
+  const v2Response = transformV1toV2(v1Response);
+
+  res.json(v2Response);
+});
+```
+
+### Deprecation Timeline
+
+```
+Month 1-3:  Announce deprecation, V2 available
+Month 4-9:  V1 marked deprecated, warnings in responses
+Month 10-12: V1 read-only, writes redirect to V2
+Month 13+:   V1 removed
+```
+
+## Version Management
+
+### Default Version
+
+```typescript
+app.use('/api/users', (req, res, next) => {
+  // Default to latest version if not specified
+  const version = req.headers['api-version'] || '2';
+  req.apiVersion = version;
+  next();
+});
+```
+
+### Version Support Matrix
+
+```typescript
+const SUPPORTED_VERSIONS = {
+  '1': {
+    status: 'deprecated',
+    sunset: '2026-01-01',
+    docs: 'https://docs.example.com/api/v1'
+  },
+  '2': {
+    status: 'current',
+    sunset: null,
+    docs: 'https://docs.example.com/api/v2'
+  },
+  '3': {
+    status: 'beta',
+    sunset: null,
+    docs: 'https://docs.example.com/api/v3'
+  }
+};
+
+app.use((req, res, next) => {
+  const version = req.apiVersion;
+  const versionInfo = SUPPORTED_VERSIONS[version];
+
+  if (!versionInfo) {
+    return res.status(400).json({
+      error: 'Unsupported API version',
+      supported_versions: Object.keys(SUPPORTED_VERSIONS)
+    });
+  }
+
+  // Add deprecation warning
+  if (versionInfo.status === 'deprecated') {
+    res.set('Warning', `299 - "API version ${version} is deprecated. Sunset: ${versionInfo.sunset}"`);
+    res.set('Sunset', versionInfo.sunset);
+  }
+
+  next();
+});
+```
+
+### Sunset Header
+
+Communicate deprecation:
+
+```http
+HTTP/1.1 200 OK
+Warning: 299 - "API v1 is deprecated. Please migrate to v2"
+Sunset: Mon, 01 Jan 2026 00:00:00 GMT
+Deprecation: true
+Link: <https://docs.example.com/migration>; rel="deprecation"
+```
+
+## GraphQL Versioning
+
+GraphQL uses schema evolution instead of versioning.
+
+### Field Deprecation
+
+```graphql
+type User {
+  id: ID!
+  name: String!
+  fullName: String!  # New field
+
+  # Deprecated field
+  user_name: String! @deprecated(reason: "Use 'name' instead")
+}
+```
+
+### Schema Directives
+
+```graphql
+directive @apiVersion(
+  added: String!
+  deprecated: String
+  removed: String
+) on FIELD_DEFINITION
+
+type User {
+  id: ID!
+  name: String! @apiVersion(added: "1.0")
+  email: String! @apiVersion(added: "2.0")
+  age: Int @apiVersion(added: "1.0", deprecated: "2.0", removed: "3.0")
+}
+```
+
+## gRPC Versioning
+
+### Package Versioning
+
+```protobuf
+// v1/user.proto
+syntax = "proto3";
+package user.v1;
+
+service UserService {
+  rpc GetUser(GetUserRequest) returns (GetUserResponse);
+}
+
+// v2/user.proto
+syntax = "proto3";
+package user.v2;
+
+service UserService {
+  rpc GetUser(GetUserRequest) returns (GetUserResponse);
+}
+```
+
+### Field Evolution
+
+```protobuf
+message User {
+  string id = 1;
+  string name = 2;
+
+  // V2: Added email
+  string email = 3;
+
+  // V3: Deprecated age (use birthdate instead)
+  int32 age = 4 [deprecated = true];
+  string birthdate = 5;
+
+  // Never reuse field numbers!
+  reserved 6, 7;  // Old fields
+  reserved "old_field";
+}
+```
+
+## Best Practices
+
+### 1. Version from Day One
+
+```typescript
+// Don't start with
+/api/users
+
+// Start with versioned endpoint
+/api/v1/users
+```
+
+### 2. Document Breaking Changes
+
+```markdown
+# V2 Migration Guide
+

package/skills/engineering/integration/refs/versioning-versioning-strategies.md

@@ -0,0 +1,296 @@
+---
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+# API Versioning Guide: Versioning Strategies
+
+## Versioning Strategies
+
+### URL Versioning
+
+Most common and explicit approach.
+
+```
+/api/v1/users
+/api/v2/users
+```
+
+**Pros**:
+- Explicit and visible
+- Easy to route
+- Browser-friendly
+- Easy to test different versions
+
+**Cons**:
+- URLs change between versions
+- Can't version individual resources differently
+
+**Implementation**:
+```typescript
+// Express.js
+app.use('/api/v1', v1Router);
+app.use('/api/v2', v2Router);
+
+// v1Router
+v1Router.get('/users/:id', (req, res) => {
+  // V1 implementation
+  res.json({
+    id: user.id,
+    name: user.name
+  });
+});
+
+// v2Router
+v2Router.get('/users/:id', (req, res) => {
+  // V2 implementation (added email)
+  res.json({
+    id: user.id,
+    name: user.name,
+    email: user.email
+  });
+});
+```
+
+### Header Versioning
+
+Version specified in request headers.
+
+```http
+GET /api/users/123
+Accept: application/vnd.myapi.v2+json
+```
+
+or
+
+```http
+GET /api/users/123
+API-Version: 2
+```
+
+**Pros**:
+- Clean URLs (don't change)
+- Can version per-resource
+- RESTful purist preference
+
+**Cons**:
+- Less visible
+- Harder to test (can't just paste URL)
+- More complex routing
+
+**Implementation**:
+```typescript
+app.get('/api/users/:id', (req, res) => {
+  const version = req.headers['api-version'] || '1';
+
+  if (version === '1') {
+    return handleV1(req, res);
+  } else if (version === '2') {
+    return handleV2(req, res);
+  }
+
+  res.status(400).json({ error: 'Unsupported API version' });
+});
+```
+
+### Query Parameter Versioning
+
+```
+/api/users?version=2
+/api/users?api-version=2
+```
+
+**Pros**:
+- Simple to implement
+- Visible in URL
+- Optional parameter
+
+**Cons**:
+- Clutters query string
+- Not as clean as URL versioning
+
+### Content Negotiation
+
+Using Accept header with custom media type.
+
+```http
+GET /api/users/123
+Accept: application/vnd.myapi.user.v2+json
+```
+
+**Pros**:
+- RESTful approach
+- Fine-grained control
+- Can version per resource type
+
+**Cons**:
+- Complex
+- Difficult to debug
+- Harder for clients to use
+
+## Semantic Versioning
+
+Use semantic versioning for API versions:
+
+```
+MAJOR.MINOR.PATCH
+
+2.1.3
+```
+
+- **MAJOR**: Breaking changes
+- **MINOR**: New features, backward compatible
+- **PATCH**: Bug fixes
+
+### Examples
+
+```
+v1.0.0 → v1.1.0   # Added new optional field
+v1.1.0 → v1.1.1   # Fixed bug in response
+v1.1.1 → v2.0.0   # Removed field (breaking)
+```
+
+### In Practice
+
+Most APIs simplify to major version only:
+
+```
+/api/v1/users
+/api/v2/users
+```
+
+Full semantic version in response headers:
+```http
+HTTP/1.1 200 OK
+API-Version: 2.1.3
+```
+
+## Backward Compatibility
+
+### Adding Fields (Safe)
+
+```typescript
+// V1 Response
+{
+  "id": "123",
+  "name": "Alice"
+}
+
+// V2 Response (added email - backward compatible)
+{
+  "id": "123",
+  "name": "Alice",
+  "email": "alice@example.com"  // New field
+}
+```
+
+Clients ignoring unknown fields will continue to work.
+
+### Making Fields Optional (Safe)
+
+```typescript
+// V1 Request
+{
+  "name": "Alice",
+  "email": "alice@example.com"  // Required
+}
+
+// V2 Request (email optional)
+{
+  "name": "Alice"
+  // email is now optional
+}
+```
+
+### Adding Optional Parameters (Safe)
+
+```typescript
+// V1
+GET /api/users?limit=10
+
+// V2 (added sort parameter)
+GET /api/users?limit=10&sort=name
+```
+
+### Deprecation (Safe)
+
+Mark fields as deprecated but keep them:
+
+```typescript
+// V2 Response
+{
+  "id": "123",
+  "name": "Alice",
+  "full_name": "Alice Smith",  // New field
+  "deprecated_name": "Alice"   // Deprecated, but still present
+}
+```
+
+## Breaking Changes
+
+### Removing Fields
+
+```typescript
+// V1 Response
+{
+  "id": "123",
+  "name": "Alice",
+  "age": 30
+}
+
+// V2 Response (removed age - BREAKING)
+{
+  "id": "123",
+  "name": "Alice"
+  // age removed
+}
+```
+
+**Solution**: Keep field but deprecate it first.
+
+### Renaming Fields
+
+```typescript
+// V1 Response
+{
+  "user_name": "Alice"
+}
+
+// V2 Response (renamed - BREAKING)
+{
+  "username": "Alice"
+}
+```
+
+**Solution**: Include both fields temporarily.
+
+### Changing Field Types
+
+```typescript
+// V1 Response
+{
+  "id": 123  // number
+}
+
+// V2 Response (changed to string - BREAKING)
+{
+  "id": "123"  // string
+}
+```
+
+**Solution**: Create new major version.
+
+### Changing Behavior
+
+```typescript
+// V1: Returns 404 if user not found
+GET /api/users/999
+Response: 404 Not Found
+
+// V2: Returns 200 with null (BREAKING)
+GET /api/users/999
+Response: 200 OK
+{ "user": null }
+```
+
+**Solution**: Document clearly and version.
+

package/skills/engineering/large-scale-migration/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: large-scale-migration
+description: How to execute a LARGE MECHANICAL change across any codebase with LEVERAGE instead of an agent-grind or hand-edits — a cross-cutting migration, refactor, rename, dialect/framework/DB port, library adoption, or bulk transform. The map→transform→gate pattern: a deterministic transform driven by a source-of-truth map, proven by a differential-equivalence gate. Use when the work is "migrate all X to Y", "rename Z everywhere", "port to a new DB/dialect/framework", "adopt a library across N files", "refactor this pattern in M places", or any change touching dozens-to-thousands of sites. Language/DB/framework-agnostic — the thinking, not a specific tool.
+---
+
+# Large-scale mechanical change — leverage, not grind
+
+A change touching dozens-to-thousands of sites is NOT N problems. It is a small number of repeated PATTERNS. Reaching for "fan out 1000 agents to edit each site", "hand-edit every file", or "sed the repo" is the paper bag. Reduce the work to **MAP → TRANSFORM → GATE** instead.
+
+## The core pattern
+
+1. **MAP** — the source of truth that already exists or can be **deterministically extracted**: an inventory of the affected sites, an ownership/registry table, a call graph, a schema. Build it with an **AST tool** (ts-morph, libcst, jscodeshift, tree-sitter, Roslyn…) or **semgrep** — never a regex string-grep (quote/escaping/comment blind spots), and never "an agent grepped and *thinks* it found them all." An exhaustive, reproducible map is the foundation; an approximate one ships a partial migration.
+2. **TRANSFORM** — a **deterministic** operation over the map: a **codemod** (AST rewrite), **codegen** (emit from the map), or **regenerate** (edit a single source-of-truth + re-run a generator that produces the derived artifacts). NOT per-site LLM editing. The transform should **preserve semantics by construction** — rewrite the call *shape* while keeping the literal; move a block intact; change the *binding* not the *logic* — so correctness is structural, not hoped-for.
+3. **GATE** — a **verifiable equivalence/green check**: **differential execution** (run old vs new on identical seeded inputs, assert identical outputs), the full test suite, or a lint count driven to 0. The change is trusted because it is **proven equivalent**, not because someone reviewed N diffs.
+
+The bulk goes through the transform. The transform **self-flags** what it can't handle (the exceptions). Humans/agents touch **only the residue** — never the bulk.
+
+## The TRANSFORM techniques menu (ranked: deterministic → AI)
+
+The TRANSFORM step is not one tool — it is a ranked ladder. **Prefer the lowest-numbered technique that fully covers the task.** Determinism is cheaper to trust than generation: a recipe or codemod preserves semantics by construction and is re-runnable; an AI wave must be eval-gated every time. Mixing rungs 80/20 across one migration is fine (most go through rung 1–2, the awkward residue through 4–5). **Never reach for rung 4/5 for what a rung-1 recipe already does** — that trades a proven transform for a hoped-for one. **Record which rung you chose** per wave, so "should I use AI here?" is a defensible, auditable decision, not an implicit one.
+
+| # | Technique | Use when |
+|---|-----------|----------|
+| 1 | **Recipe** (e.g. OpenRewrite, ts-morph preset, framework upgrade-assistant) | A well-known, parameterized transform already exists for this exact change (version bump, API rename, framework migration). Highest leverage, lowest risk — adopt it. |
+| 2 | **AST codemod** (jscodeshift, libcst, tree-sitter, Roslyn, ts-morph) | No off-the-shelf recipe, but the change is a structural rewrite expressible as a tree operation (rewrite the call *shape*, move a block intact, change a binding). Deterministic, semantics-preserving by construction. |
+| 3 | **Pattern-replace / codegen / regenerate** | The change is driven by a source-of-truth map — emit the derived artifacts from the map, or edit the single source + re-run a generator. (Structured replace only; **never** raw `sed`/regex on code — string blind spots break semantics silently.) |
+| 4 | **AI-assisted wave (eval-gated)** | The transform needs judgment a tree op can't encode (idiomatic re-expression, semantic translation across a paradigm gap) but is still bulk-shaped. Run it in waves, each **gated by the differential-equivalence check** — never ship an AI wave on a build-green alone. |
+| 5 | **Manual + AI pair** | Genuinely non-portable / one-off residue the transform self-flagged (cross-cutting joins, sync/async boundaries, non-portable platform features). Judgment-only, case-by-case — the *smallest* slice, never the bulk. |
+
+The GATE is the same regardless of rung: differential equivalence (or suite-green / lint-to-0) is what makes the change trustworthy. A higher rung does not lower the bar — it raises it (rungs 4–5 need *more* fixture coverage, not less).
+
+## Before you transform: make the INSTRUMENT trustworthy
+You cannot drive a count to 0 if the count is a fiction. Fix the *measurement* FIRST:
+- Does the lint/audit/inventory actually see **all** the cases? Prove it: inject a known violation and confirm it's caught. (Real failure mode: a "complete" audit that masked single-quoted strings and silently under-counted by hundreds.)
+- Is the **baseline** the right one? Diffing the after-state against a baseline that *already contains part of the change* catches nothing — pin the true before-state.
+
+## Buy / rewrite / build — not "write more code"
+Solve for the OUTCOME with maximum leverage, per sub-problem:
+- An **OSS component** that meets the requirement beats building it — a query builder, an **in-process embedded engine** for tests (so the test→fix loop needs no infra), a parser/translator. Adopt it; build only the thin seam it doesn't cover.
+- A clean **rewrite** of a section (you have the working code as the spec) beats editing it in place across dozens of touch-points.
+
+## The rules (non-negotiable)
+- **No grandfathering.** "Done" = the count is 0 **AND** zero exemptions (suppressions / allow-markers / "left raw with a TODO / DEFERRAL"). Fix the code; never exempt it. An exemption is a landmine that *defeats the migration's purpose* — it preserves the exact case the migration exists to remove, and it stays invisible until it breaks.
+- **Differential equivalence is the trust — not review.** `old(input) === new(input)` on real seeded data. Strength tracks fixture coverage → seed broadly; an empty fixture passes trivially and lies.
+- **Residue is small, self-flagged, judgment-only.** The transform reports what it couldn't do; that list is the only place to reason case-by-case (cross-cutting joins, genuinely non-portable constructs, sync/async boundaries).
+- **Prove the runtime — don't trust build-green.** Build/test green ≠ feature works, *especially* for LLM/agent features (the assembled context can drift while stored rows stay byte-identical → degraded reasoning / hallucination that no unit test catches). Prove the running process serves the right build; **grade** functional outputs (content correctness + faithfulness), don't just check a 200-OK.
+- **No implicit completeness, and never narrow the DoD to skip work.** Name what is NOT done. If a phase can't reach its green gate, STOP there and name the blocker — do not declare a convenient subset "done."
+
+## Worked example (transferable): a data-access migration → second engine
+Goal: move ~1,900 raw `db.prepare(sql)`-style call sites behind one typed port, then run the app on a second DB engine/dialect — without hand-editing 1,900 sites or standing up infra.
+- **MAP:** an AST extractor walks the *call expressions* (matching the call node, not string contents → no quote blind spot) → an exhaustive inventory of every query, its tables, and static-vs-dynamic shape.
+- **TRANSFORM:** a codemod rewrites the call *shape* (e.g. positional `?` → named params; SQL literal preserved) and injects the port; the sync→async cascade propagates up the call graph; sync-boundaries self-flag for manual handling.
+- **GATE:** a differential test runs the OLD query and the NEW port call against the **same seeded in-memory DB** and asserts byte-identical results (rows + affected-rows + resulting state). Per-module then full-suite green is the bar.
+- **Second engine:** adopt an **in-process embedded build of the target engine** for tests (no server), translate **only** the non-portable patterns the inventory *proves* exist (dialect translation at the adapter boundary), and route truly-non-portable features (full-text, vector) behind **thin adapter interfaces**. The **cross-engine differential** (same query, both engines, equivalent) is the gate.
+- **Same pattern, different map, per phase:** correcting an *ownership/registry map* = edit the single source-of-truth + **regenerate** the derived artifacts (never hand-edit the derivatives). Relocating code by an ownership map = a codemod keyed on that map. Isolating onto separate connections/processes = a **config flip** on a registry the port already abstracts (no code rewrite — that's the payoff of routing everything through the port first).
+
+## Anti-patterns this kills
+- "Fan out 1,000 agents to hand-edit each site" — context blow-up, non-deterministic, no equivalence proof.
+- "sed / regex replace across the repo" — string blind spots, false positives, breaks semantics silently.
+- "Exempt the hard ones / leave a TODO / suppress the lint" — grandfathering, the landmine.
+- "Build green + suite green, ship it" — never proved the feature, never proved the runtime.
+- "This subset counts as done" — narrowing the DoD to skip work.
+
+## Pair with (if your project has them)
+A "prove the feature works, not just build-green" discipline; a "no silent failures" discipline; and a recorded "definition of done" you refuse to narrow.