wicked-garden 12.27.0

package/skills/engineering/system-design/refs/patterns-layered-pattern.md

@@ -0,0 +1,204 @@
+---
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+# Component Design Patterns: Layered Pattern
+
+## Layered Pattern
+
+### Structure
+
+```
+┌─────────────────────────┐
+│   Presentation Layer    │  Controllers, Views, API
+├─────────────────────────┤
+│   Application Layer     │  Use Cases, Workflows
+├─────────────────────────┤
+│     Domain Layer        │  Business Logic, Entities
+├─────────────────────────┤
+│  Infrastructure Layer   │  Database, External Services
+└─────────────────────────┘
+```
+
+### Example
+
+```typescript
+// Presentation Layer (API Controller)
+class UserController {
+  constructor(private userService: UserService) {}
+
+  async createUser(req: Request, res: Response) {
+    const result = await this.userService.createUser(req.body);
+    res.status(201).json(result);
+  }
+}
+
+// Application Layer (Service)
+class UserService {
+  constructor(
+    private userRepo: UserRepository,
+    private emailService: EmailService
+  ) {}
+
+  async createUser(data: CreateUserDTO): Promise<User> {
+    // Application logic
+    const user = User.create(data);
+    await this.userRepo.save(user);
+    await this.emailService.sendWelcome(user.email);
+    return user;
+  }
+}
+
+// Domain Layer (Entity)
+class User {
+  constructor(
+    public id: string,
+    public email: string,
+    public name: string
+  ) {
+    this.validate();
+  }
+
+  private validate() {
+    if (!this.email.includes('@')) {
+      throw new Error('Invalid email');
+    }
+  }
+
+  static create(data: { email: string; name: string }): User {
+    return new User(generateId(), data.email, data.name);
+  }
+}
+
+// Infrastructure Layer (Repository)
+class PostgresUserRepository implements UserRepository {
+  async save(user: User): Promise<void> {
+    await db.query(
+      'INSERT INTO users (id, email, name) VALUES ($1, $2, $3)',
+      [user.id, user.email, user.name]
+    );
+  }
+}
+```
+
+### When to Use
+
+- Traditional web applications
+- Need clear separation of concerns
+- Team familiar with MVC
+- Moderate complexity
+
+### Trade-offs
+
+**Pros**: Easy to understand, well-known pattern
+**Cons**: Can become rigid, may lead to anemic models
+
+## Hexagonal (Ports & Adapters)
+
+### Structure
+
+```
+            ┌──────────────┐
+            │   REST API   │ (Adapter)
+            └──────┬───────┘
+                   │
+        ┌──────────▼──────────┐
+        │    Port (Interface) │
+        ├─────────────────────┤
+        │                     │
+        │   Business Logic    │
+        │    (Core Domain)    │
+        │                     │
+        ├─────────────────────┤
+        │ Port (Interface)    │
+        └──────────┬──────────┘
+                   │
+        ┌──────────┼──────────┐
+        │          │          │
+   ┌────▼───┐ ┌───▼────┐ ┌──▼────┐
+   │Postgres│ │ Redis  │ │  S3   │ (Adapters)
+   └────────┘ └────────┘ └───────┘
+```
+
+### Example
+
+```typescript
+// Port (Interface)
+interface UserRepository {
+  save(user: User): Promise<void>;
+  findById(id: string): Promise<User | null>;
+  findByEmail(email: string): Promise<User | null>;
+}
+
+// Core Domain (Business Logic)
+class UserService {
+  constructor(
+    private userRepo: UserRepository,  // Depends on port, not adapter
+    private emailGateway: EmailGateway
+  ) {}
+
+  async registerUser(email: string, name: string): Promise<User> {
+    // Pure business logic
+    const existing = await this.userRepo.findByEmail(email);
+    if (existing) {
+      throw new Error('Email already registered');
+    }
+
+    const user = User.create(email, name);
+    await this.userRepo.save(user);
+    await this.emailGateway.sendWelcome(user.email);
+
+    return user;
+  }
+}
+
+// Adapter (Implementation)
+class PostgresUserRepository implements UserRepository {
+  async save(user: User): Promise<void> {
+    await db.query('INSERT INTO users ...');
+  }
+
+  async findById(id: string): Promise<User | null> {
+    const row = await db.query('SELECT * FROM users WHERE id = $1', [id]);
+    return row ? User.fromRow(row) : null;
+  }
+
+  async findByEmail(email: string): Promise<User | null> {
+    const row = await db.query('SELECT * FROM users WHERE email = $1', [email]);
+    return row ? User.fromRow(row) : null;
+  }
+}
+
+// Another Adapter (for testing)
+class InMemoryUserRepository implements UserRepository {
+  private users = new Map<string, User>();
+
+  async save(user: User): Promise<void> {
+    this.users.set(user.id, user);
+  }
+
+  async findById(id: string): Promise<User | null> {
+    return this.users.get(id) || null;
+  }
+
+  async findByEmail(email: string): Promise<User | null> {
+    for (const user of this.users.values()) {
+      if (user.email === email) return user;
+    }
+    return null;
+  }
+}
+```
+
+### When to Use
+
+- Need to isolate business logic
+- Frequent technology changes
+- Testing is critical
+- Multiple interfaces (API, CLI, Worker)
+
+### Trade-offs
+
+**Pros**: Highly testable, technology-agnostic core
+**Cons**: More abstraction, may be overkill for simple apps
+

package/skills/engineering/system-design/refs/patterns-plugin-architecture.md

@@ -0,0 +1,229 @@
+---
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+# Component Design Patterns: Plugin Architecture
+
+## Plugin Architecture
+
+### Structure
+
+```
+┌────────────────────────────┐
+│       Core System          │
+│  (Minimal, Stable)         │
+└────────┬───────────────────┘
+         │
+         │ Plugin Interface
+         │
+    ┌────┼────┬────────┬──────┐
+    │    │    │        │      │
+┌───▼┐ ┌─▼──┐ ┌▼────┐ ┌▼────┐
+│P1  │ │ P2 │ │ P3  │ │ P4  │
+└────┘ └────┘ └─────┘ └─────┘
+```
+
+### Example
+
+```typescript
+// Core System
+interface Plugin {
+  name: string;
+  version: string;
+  init(app: Application): Promise<void>;
+  shutdown(): Promise<void>;
+}
+
+class PluginManager {
+  private plugins: Map<string, Plugin> = new Map();
+
+  async register(plugin: Plugin): Promise<void> {
+    if (this.plugins.has(plugin.name)) {
+      throw new Error(`Plugin ${plugin.name} already registered`);
+    }
+
+    await plugin.init(this.app);
+    this.plugins.set(plugin.name, plugin);
+  }
+
+  async unregister(name: string): Promise<void> {
+    const plugin = this.plugins.get(name);
+    if (!plugin) return;
+
+    await plugin.shutdown();
+    this.plugins.delete(name);
+  }
+
+  getPlugin(name: string): Plugin | undefined {
+    return this.plugins.get(name);
+  }
+}
+
+// Plugin Implementation
+class AuthPlugin implements Plugin {
+  name = 'auth';
+  version = '1.0.0';
+
+  async init(app: Application): Promise<void> {
+    // Register routes
+    app.post('/auth/login', this.handleLogin);
+    app.post('/auth/logout', this.handleLogout);
+
+    // Register middleware
+    app.use(this.authMiddleware);
+  }
+
+  async shutdown(): Promise<void> {
+    // Cleanup
+  }
+
+  private handleLogin = async (req, res) => {
+    // Login logic
+  };
+
+  private handleLogout = async (req, res) => {
+    // Logout logic
+  };
+
+  private authMiddleware = async (req, res, next) => {
+    // Auth checking
+    next();
+  };
+}
+
+// Usage
+const pluginManager = new PluginManager(app);
+await pluginManager.register(new AuthPlugin());
+await pluginManager.register(new PaymentPlugin());
+await pluginManager.register(new NotificationPlugin());
+```
+
+### When to Use
+
+- Extensibility is a key requirement
+- Third-party extensions needed
+- Feature sets vary by deployment
+- Plugin marketplace desired
+
+### Trade-offs
+
+**Pros**: Highly extensible, loose coupling
+**Cons**: Plugin compatibility, security concerns
+
+## Repository Pattern
+
+### Structure
+
+```
+┌─────────────┐
+│   Service   │
+└──────┬──────┘
+       │
+       │ Interface
+       │
+┌──────▼──────┐
+│ Repository  │ (Abstraction)
+└──────┬──────┘
+       │
+       │ Implementation
+       │
+┌──────▼──────┐
+│  Database   │
+└─────────────┘
+```
+
+### Example
+
+```typescript
+// Repository Interface
+interface UserRepository {
+  findById(id: string): Promise<User | null>;
+  findAll(filter?: UserFilter): Promise<User[]>;
+  save(user: User): Promise<void>;
+  delete(id: string): Promise<void>;
+}
+
+// Domain Entity
+class User {
+  constructor(
+    public id: string,
+    public email: string,
+    public name: string,
+    public status: 'active' | 'inactive'
+  ) {}
+}
+
+// Repository Implementation
+class PostgresUserRepository implements UserRepository {
+  constructor(private db: Database) {}
+
+  async findById(id: string): Promise<User | null> {
+    const row = await this.db.queryOne(
+      'SELECT * FROM users WHERE id = $1',
+      [id]
+    );
+
+    return row ? this.mapToEntity(row) : null;
+  }
+
+  async findAll(filter?: UserFilter): Promise<User[]> {
+    const query = this.buildQuery(filter);
+    const rows = await this.db.query(query.sql, query.params);
+    return rows.map(row => this.mapToEntity(row));
+  }
+
+  async save(user: User): Promise<void> {
+    await this.db.query(
+      `INSERT INTO users (id, email, name, status)
+       VALUES ($1, $2, $3, $4)
+       ON CONFLICT (id) DO UPDATE
+       SET email = $2, name = $3, status = $4`,
+      [user.id, user.email, user.name, user.status]
+    );
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.db.query('DELETE FROM users WHERE id = $1', [id]);
+  }
+
+  private mapToEntity(row: any): User {
+    return new User(row.id, row.email, row.name, row.status);
+  }
+
+  private buildQuery(filter?: UserFilter) {
+    // Query building logic
+    return { sql: '...', params: [] };
+  }
+}
+
+// Service using repository
+class UserService {
+  constructor(private userRepo: UserRepository) {}
+
+  async getActiveUsers(): Promise<User[]> {
+    const users = await this.userRepo.findAll({ status: 'active' });
+    return users;
+  }
+
+  async activateUser(id: string): Promise<void> {
+    const user = await this.userRepo.findById(id);
+    if (!user) throw new Error('User not found');
+
+    user.status = 'active';
+    await this.userRepo.save(user);
+  }
+}
+```
+
+### When to Use
+
+- Need to abstract data access
+- Multiple data sources possible
+- Domain-driven design
+- Testing with mock data
+
+### Trade-offs
+
+**Pros**: Decouples business logic from data access
+**Cons**: Additional abstraction layer
+

package/skills/engineering/unit-test-quality/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: unit-test-quality
+description: |
+  Language- and framework-neutral guard against useless unit tests — the kind
+  that pass forever, never catch regressions, and inflate coverage without
+  protecting behavior. Provides two complementary thought-experiment filters
+  (execution + behavior), a pre-write self-check, a taxonomy of seven recurring
+  anti-patterns (tautological, assertion-free, implementation mirror, framework
+  retest, constant verification, sleep-coupled, exception-swallowing), and a
+  one-line decision rule per pattern.
+
+  Use when: writing or reviewing a unit test, auditing a suite with high
+  coverage but low confidence, or pairing a regression test with a bug fix.
+status: stable
+portability: portable
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+
+# Unit Test Quality
+
+A test you cannot break by changing the system under test (SUT) is not a test —
+it is dead weight. This skill exists because suites grow faster than they shrink,
+and "100% coverage" is no defense against a suite that asserts the wrong things.
+
+## Two complementary filters
+
+No single mechanical filter catches every useless test — each anti-pattern
+below has its own diagnostic. But two thought experiments catch the most common
+cases and are language-neutral. Apply them in order; if either says "cut," you
+are looking at a test that does not earn its keep.
+
+### Filter A — execution check
+
+> **If I replace the body of the SUT with a force-fail (`throw` / `raise` / `panic` / equivalent), does the test still pass?**
+
+- **Still passes** → the test never exercised the SUT at all. Cut it (it is pure coverage theater, see #2 assertion-free, #4 framework retest).
+- **Now fails** → the test at least *invokes* the SUT. Move to Filter B.
+
+### Filter B — behavior check
+
+> **If I replace the body of the SUT with a no-op stub returning sensible defaults (zero, null/None, empty collection, default-constructed value), does the test still pass?**
+
+- **Still passes** → the test asserts nothing the SUT actually computes; the assertion would hold against an empty stub. Cut it (typically #5 constant verification or #4 framework retest).
+- **Now fails** → the test depends on SUT-derived behavior. Likely worth keeping, but still apply the per-pattern rules below.
+
+The filters are first-cut diagnostics — both can pass on #1 tautological (assertion mirrors mock input), #3 implementation mirror (assertion locks structure, not behavior), #6 sleep-coupled (timing flake is orthogonal), and #7 exception-swallowing (assertion-count guards are required regardless). Use the per-pattern decision rules below for those.
+
+## The seven useless-test anti-patterns
+
+### 1. Tautological — asserts what the mock was told to return
+
+```
+when(repo.find(1)).thenReturn(user);
+result = service.fetch(1);
+assert(result == user);   // Tests that the mock was wired correctly. The
+                          // production fetch() could be `return repo.find(id)`
+                          // OR `return repo.find(id).asJson().broken()` — this
+                          // test cannot distinguish.
+```
+
+**Decision rule:** if the assertion is about a value you handed to a mock, the
+test asserts mock plumbing, not behavior. Replace with a contract assertion
+(state changed, side-effect emitted, derived value computed).
+
+### 2. Assertion-free — "no exception thrown" is the only signal
+
+```
+test("processes order", () => {
+  service.process(order);            // No assertion. Coverage counter ticks.
+});
+```
+
+**Decision rule:** every test must contain a positive assertion against an
+observable outcome. If the only thing the test proves is "this line executed",
+delete it — coverage tools already prove that.
+
+Variants to catch: `expect(x).toBeDefined()`, `expect(x).not.toBeNull()`,
+`assert x is not None`, `assertNotNull(x)`. These are coverage assertions, not
+behavior assertions.
+
+### 3. Implementation mirror — asserts the structure of the code, not its outcome
+
+```
+expect(component.props).toEqual({a: 1, b: 2, c: 3, d: 4, e: 5});
+```
+
+**Decision rule:** snapshot tests and full-object equals tests rot — they catch
+*every* change, including refactors that preserve behavior. Assert the
+*minimum* set of fields that prove the contract. If the test must update every
+time the SUT is touched, the test is locking in implementation, not behavior.
+
+### 4. Framework retest — asserts that the framework still works
+
+```
+test("ORM saves user", () => {
+  user = User.create({name: "x"});
+  assert(User.find(user.id).name == "x");   // Tests Rails / Django / Hibernate.
+});
+```
+
+**Decision rule:** the framework's test suite covers this. If your test would
+also pass against an empty stub of *your* code, it is a framework test. Move
+it to integration tests if the wiring is non-trivial; otherwise delete it.
+
+### 5. Constant verification — tests with no logic
+
+```
+test("getter returns name", () => {
+  user = new User("alice");
+  expect(user.name).toBe("alice");
+});
+```
+
+**Decision rule:** if the SUT contains no branches, no transformations, no
+side-effects, and no derivations, there is nothing to test. Generated getters,
+data-class field access, and one-line returns of constants do not need unit
+tests.
+
+### 6. Sleep-coupled — uses `sleep`, `setTimeout`, or wall-clock waits to "stabilize"
+
+```
+service.startBackground();
+sleep(500);                  // Hopes the background work finished.
+expect(state).toBe("done");
+```
+
+**Decision rule:** any test using a hardcoded delay is non-deterministic. Either
+the test sometimes finishes before the SUT (false fail), sometimes finishes
+exactly on the boundary (flake), or runs unnecessarily slowly (waste). Replace
+with: a deterministic clock, an explicit completion signal, or a poll-with-timeout
+over a real condition (not a sleep).
+
+### 7. Exception-swallowing — try/catch hides the failure
+
+```
+test("handles bad input", () => {
+  try { service.process(null); } catch (e) { /* expected */ }
+});
+```
+
+**Decision rule:** assertions that depend on a `catch` block being entered must
+*also* assert the catch was entered (`expect.assertions(N)` in Jest, `try…else` in
+Python with a fail-the-test in `else`). A bare `catch` that swallows everything
+makes the test pass even when the SUT fails to throw at all.
+
+## Pre-write self-check (use before adding a new test)
+
+Run through these in order. Stop at the first "no" — that is the work to do
+before writing the test.
+
+1. **What contract am I asserting?** State it in one sentence: input → expected
+   observable outcome. If you cannot, you are not yet ready to write the test.
+2. **Could this test pass against a broken SUT?** Mentally apply Filter A
+   (replace SUT body with a force-fail) and Filter B (replace SUT body with a
+   no-op default-returning stub). If the test passes either filter, stop and
+   reconsider what you are asserting.
+3. **Is the assertion about behavior or about plumbing?** Behavior: state
+   changed, value derived, event emitted, error raised with specific shape.
+   Plumbing: mock was called, function exists, framework worked.
+4. **Is there exactly one logical assertion?** Multiple assertions about the
+   same outcome are fine; multiple unrelated outcomes mean multiple tests.
+5. **Is the test deterministic without sleeps?** If it depends on timing,
+   reach for a fake clock or a completion signal, not a delay.
+6. **Will I have to update this test on every refactor?** If yes, it is asserting
+   implementation, not behavior. Narrow the assertion.
+7. **Does the test name describe the behavior?** "test_user_creation" is a
+   coverage label. "rejects user creation when email is missing" is a contract.
+
+## Reviewer rubric (use during PR review of new tests)
+
+For each new test in the diff:
+
+- Read the test name. Does it state a contract or a code path? Contract → continue. Code path → flag.
+- Read the assertion(s). Are they against observable outcomes the SUT controls? Yes → continue. No → flag.
+- Apply Filter A mentally. Would the test fail if the SUT body became a force-fail (throw/raise/panic)? Yes → continue. No → flag (#2 assertion-free or #4 framework retest).
+- Apply Filter B mentally. Would the test fail if the SUT body became a no-op stub returning defaults? Yes → likely keep. No → flag (#5 constant verification or #4 framework retest).
+- If the test uses a mock: does the assertion verify *interaction the SUT chose to make*, not *value the test handed in*? Verifies SUT decision → keep. Echoes test input → flag (#1 tautological — neither filter catches this; structural inspection only).
+- If the test contains `sleep`, `setTimeout(..., N)`, `Thread.sleep`, `time.sleep`, `await delay`, or any wall-clock-based wait: flag (#6 sleep-coupled). Replace with fake timers / virtual clock, an explicit completion signal/promise, or a poll-with-timeout over a real condition — never with `setTimeout(..., 0)` (which is a macrotask, not deterministic).
+
+## What this skill does not cover
+
+- **Integration / E2E tests** — different rules (real dependencies, slower feedback, broader contracts). Use the `integration` skill.
+- **Property / fuzz testing** — requires its own taxonomy (shrinking, generators, invariants). Out of scope here.
+- **Mutation testing** — verifies the *suite* catches bugs by mutating the SUT. Use the `mutation-test-engineer` agent for that audit; this skill prevents the bad tests in the first place.
+- **Test runner / CI ergonomics** — flake quarantine, retry policy, parallel isolation. See the `flaky-test-hunter` agent.
+
+## Why this is one skill across all languages
+
+The seven anti-patterns above show up in pytest, Jest, Vitest, JUnit, RSpec,
+xUnit, Go's `testing`, Rust's `#[test]`, and every framework that has ever
+shipped. The syntax differs; the failure mode is identical. Keeping the rules
+language-neutral is what makes this skill durable — any new framework inherits
+the same filters the day it is adopted.