wicked-garden 12.27.0

package/skills/engineering/refs/plan.md

@@ -0,0 +1,109 @@
+# plan — implementation planning rubric
+
+Checklist and output format for generating detailed implementation plans with file changes,
+risk assessment, and test recommendations before writing code.
+
+## Pre-plan exploration checklist
+
+Before drafting a plan, explore the codebase to understand:
+
+- [ ] Files that implement the functionality being changed
+- [ ] Direct callers and consumers of those files (blast radius)
+- [ ] Existing patterns and conventions (naming, error handling, module structure)
+- [ ] Test patterns and coverage for affected areas
+- [ ] Any feature flags or config that gates the change
+
+Use `wicked-garden:search:blast-radius {symbol}` to find all call sites. Fall back to
+`wicked-brain:search` or Grep when the index is unavailable.
+
+## Risk assessment checklist
+
+For each change, evaluate:
+
+| Risk Category | Questions to ask |
+|---------------|-----------------|
+| Breaking changes | Does this change any public interface, event schema, or API contract? |
+| Performance | Does this add I/O, a loop, or a DB query to a hot path? |
+| Security | Does this touch auth, session, credentials, or user-supplied input? |
+| Data integrity | Does this touch a migration, schema, or data transform? |
+| Test gaps | Are there untested edge cases that the change could break? |
+| Deployment | Does this require a coordinated deploy (e.g. schema before code)? |
+
+## Implementation plan output format
+
+```markdown
+## Implementation Plan: {title}
+
+### Summary
+{1-2 sentence overview of what changes and why}
+
+### Scope
+- **In scope**: {what will change}
+- **Out of scope**: {explicitly NOT changing}
+
+### Changes Required
+
+#### 1. {path/to/file.ext}
+**Purpose**: {why this file changes}
+**Changes**:
+- {Specific change — e.g., "Add null check before accessing `.id`"}
+- {Add / Modify / Remove — be concrete}
+
+#### 2. {path/to/another-file.ext}
+**Purpose**: {why}
+**Changes**:
+- {change}
+
+### Risk Assessment
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| {risk} | Low/Med/High | Low/Med/High | {action} |
+
+### Test Plan
+
+- [ ] Unit: {what unit behavior to cover}
+- [ ] Integration: {what flow to exercise end-to-end}
+- [ ] Manual verification: {scenario to check in the running app}
+- [ ] Regression: {existing tests to re-run}
+
+### Rollout Considerations
+
+{Any deployment notes: feature flags, migration order, canary, backward compatibility window}
+
+### Open Questions
+
+- {Question that needs resolution before implementation starts}
+```
+
+## Planning heuristics
+
+**Start with the test** — if you can't describe what test would fail without this change,
+the requirement isn't specific enough yet.
+
+**One file at a time** — each file in "Changes Required" should have its own purpose;
+if two files have the same purpose, merge them in the plan.
+
+**Flag unauthorized scope** — if exploration reveals the change will require touching
+files well outside the stated scope, surface this before proceeding.
+
+**Security checklist for any change touching auth, input, or data**:
+- [ ] No credentials logged
+- [ ] Input validated before use
+- [ ] Authorization checked (not just authentication)
+- [ ] SQL/injection-safe if DB queries change
+- [ ] No plaintext secrets in new config
+
+**Performance checklist for any change on a hot path**:
+- [ ] No new synchronous I/O added to request path
+- [ ] No N+1 query pattern introduced
+- [ ] Timeout specified on any new external call
+- [ ] No unbounded collection loaded into memory
+
+## After presenting the plan
+
+Ask:
+> Ready to proceed with implementation, or would you like to adjust the approach?
+
+If approved, execute using `engineering:apply` or the build archetype
+(`/wicked-garden:archetype:build`).

package/skills/engineering/refs/review.md

@@ -0,0 +1,138 @@
+# review — senior engineering code review rubric
+
+Bulletproof Standards (R1–R6 + T1–T6), severity guidelines, persona routing, and output format.
+Use `engineering:review` for code-level review; use `engineering:arch` for component/system architecture review.
+
+## Bulletproof Coding Standards — R1–R6
+
+These are enforcement directives, not suggestions. Flag every violation. No exceptions.
+
+- **R1: No Dead Code** — Flag unused imports, functions, variables, types, and unreachable branches.
+  Dead code decays, misleads, and costs. Delete it, or add a comment explaining why it stays.
+
+- **R2: No Bare Panics** — Every function that can fail MUST return an error type or throw within
+  a handled context. No `panic()`, no unhandled exceptions, no `unwrap()` in production paths,
+  no `process.exit(1)` in library code. If it can fail, the signature must show it.
+
+- **R3: No Magic Values** — All constants must be named. No bare numbers, strings, or config values
+  in logic. Examples to flag: `if retries > 3`, `timeout: 5000`, `color: '#1a1a2e'`, `z-index: 9999`.
+  Demand a named constant with a comment explaining the choice.
+
+- **R4: No Swallowed Errors** — Every error catch must handle or propagate. Empty catch blocks,
+  `_ = err`, `pass`, and `console.log(err)` without user feedback are violations. "Log and continue"
+  counts only if the log includes the error detail and the function's contract allows partial failure.
+
+- **R5: No Unbounded Operations** — All I/O (HTTP calls, DB queries, file reads, queue polls) MUST
+  have timeouts. No indefinite `await`, no missing `context.WithTimeout`, no fetch without
+  `AbortController` or `signal`, no infinite retries without backoff and ceiling. External calls
+  need a timeout AND a failure mode.
+
+- **R6: No God Functions** — Functions over ~60 lines need extraction. More than 3 nesting levels
+  needs early returns or decomposition. If you can't describe what a function does in one sentence,
+  it does too much.
+
+## Bulletproof Testing Standards — T1–T6
+
+Apply when `--focus tests` or when reviewing test files directly.
+
+- **T1: Determinism** — No date/time dependencies without injected clocks. No random without seed.
+  No order-dependent test suites. Same input → same result, always.
+
+- **T2: No sleep-based sync** — No `sleep(200)` or `time.Sleep` as a synchronization mechanism.
+  Use explicit waits, callbacks, events, or polling with a timeout and an error on timeout.
+
+- **T3: Isolation** — Each test sets up and tears down its own state. No shared mutable globals
+  between tests. No dependency on test execution order.
+
+- **T4: Single assertion focus** — One logical assertion per test (multiple asserts on the same
+  subject is fine). Tests that assert five unrelated things make failures hard to diagnose.
+
+- **T5: Descriptive names** — Test name should read as a sentence: `test_returns_empty_list_when_no_users`,
+  not `test_user_3`. Name should encode: subject + scenario + expected outcome.
+
+- **T6: Provenance** — Each test should trace to a requirement, acceptance criterion, or bug ID.
+  Tests without clear purpose are maintenance debt. Note the gap as LOW severity.
+
+## Agent overstepping — always flag
+
+- Unrelated edits outside stated scope
+- Commented-out code left in the diff
+- Over-engineering / speculative generality (YAGNI violations)
+- Scope creep: restructuring files not mentioned in the task
+- Refactoring mixed into a bug fix (makes rollback impossible)
+
+## Focus lanes (applied when `--focus` given)
+
+| Flag | Deepen these areas |
+|------|-------------------|
+| `--focus security` | Auth/authz, input validation, SQL injection, credential handling, OWASP Top 10 |
+| `--focus performance` | Hot paths, N+1 queries, missing indexes, unbounded ops, caching opportunities |
+| `--focus patterns` | DRY, SOLID, naming, abstractions, module boundaries, coupling |
+| `--focus tests` | T1–T6 standards, coverage gaps, flakiness risks, missing edge cases |
+
+## Persona routing (`--persona <name>`)
+
+1. Resolve the persona:
+   ```bash
+   PERSONA_JSON=$(sh "${CLAUDE_PLUGIN_ROOT}/scripts/_python.sh" "${CLAUDE_PLUGIN_ROOT}/scripts/_run.py" scripts/persona/registry.py --get "${persona_name}" --json 2>/dev/null)
+   ```
+2. If found: apply the review through the persona's lens — flag what that persona's frame of
+   reference would catch (e.g. a security-focused persona finds auth gaps a general review might
+   rate LOW).
+3. If not found: warn "Persona '{name}' not found — using default review lens" and fall through.
+
+## wicked-scenarios (`--scenarios`)
+
+For each Critical or High finding, emit a wicked-scenarios regression block:
+
+```yaml
+scenario: "{title describing the bug/issue}"
+given: "{precondition}"
+when: "{action that triggers it}"
+then: "{expected behavior after fix}"
+file: "{file}:{line}"
+severity: "Critical|High"
+```
+
+## Standard output format
+
+```markdown
+## Engineering Review: {scope or file}
+
+### Strengths
+- {good pattern with file:line evidence}
+
+### Issues
+
+| Severity | Rule | Issue | Location | Recommendation |
+|----------|------|-------|----------|----------------|
+| CRITICAL/HIGH/MEDIUM/LOW | R1–R6 or T1–T6 | {description} | `{file}:{line}` | {concrete fix} |
+
+### Architecture Notes
+{Any structural observations — use engineering:arch for full analysis}
+
+### Maintainability Concerns
+{Long-term maintenance considerations}
+
+### Agent Overstepping
+{Any out-of-scope edits, commented-out code, or scope creep found — cite file:line}
+
+### Recommendations
+1. {Highest priority with rationale}
+2. {Secondary}
+```
+
+## Severity guidelines
+
+- **CRITICAL**: Will cause data loss, security breach, or production outage
+- **HIGH**: Will cause bugs, broken patterns, or major maintainability problems
+- **MEDIUM**: Should fix; will accumulate tech debt; non-blocking
+- **LOW**: Nice to have; style; minor improvements; provenance gaps
+
+## Cross-specialist referrals
+
+- Security deep-dive → `wicked-garden:platform:security-engineer`
+- Testing strategy → `wicked-testing:test-strategist`
+- Architecture / structural trade-offs → `wicked-garden:engineering:solution-architect`
+- Frontend specifics (React hooks, CSS, a11y), backend specifics (DB, API design,
+  queues): handled inline — apply the relevant checklist from this skill's refs.

package/skills/engineering/system-design/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: system-design
+description: |
+  Use when decomposing a system into components with clear boundaries, module organization, and interface
+  contracts — the "how do we slice this?" question at design time.
+  NOT for reviewing an existing system's health (use the architecture skill or engineering:arch).
+portability: portable
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+
+# System Design Skill
+
+Decompose systems into well-defined components with clear boundaries and interfaces.
+
+## Purpose
+
+Transform architecture into concrete components:
+- Component identification and boundaries
+- Interface definition
+- Dependency management
+- Module organization
+
+## Process
+
+### 1. Identify Components
+
+Ask:
+- What are major capabilities?
+- What changes together?
+- What has different scaling needs?
+- What domain concepts exist?
+
+### 2. Define Boundaries
+
+Apply:
+- **High Cohesion** - Related functionality together
+- **Low Coupling** - Minimal dependencies
+- **Single Responsibility** - One reason to change
+- **Information Hiding** - Encapsulate internals
+
+### 3. Design Interfaces
+
+For each component:
+- Public API (what it exposes)
+- Dependencies (what it needs)
+- Events (what it publishes/subscribes)
+- Data contracts (I/O structures)
+
+### 4. Document
+
+Creates in `phases/design/`:
+```
+design/
+├── components/
+│   ├── overview.md
+│   ├── auth-component.md
+│   └── dependencies.mmd
+└── interfaces/
+    └── component-api.md
+```
+
+## Component Patterns
+
+**Layered** - Presentation → Application → Domain → Infrastructure
+**Hexagonal** - Business logic with adapter ports
+**Plugin** - Core system with pluggable extensions
+
+See component patterns in refs/ (patterns-layered-pattern.md, patterns-facade-pattern.md).
+
+## Dependency Management
+
+### Rules
+
+1. **Acyclic** - No circular dependencies
+2. **Unidirectional** - Dependencies flow one way
+3. **Stable** - Depend on stable abstractions
+4. **Explicit** - Declare in constructor/config
+
+### Common Anti-Patterns
+
+**God Object** - One component does everything
+**Fix**: Split by responsibility
+
+**Feature Envy** - Component uses another's data extensively
+**Fix**: Move functionality to data owner
+
+**Circular Dependencies** - A depends on B, B depends on A
+**Fix**: Extract shared logic or use events
+
+**Leaky Abstraction** - Internal details exposed
+**Fix**: Refine public interface
+
+See dependency guides in refs/ (dependencies-dependency-principles.md, dependencies-best-practices.md).
+
+## Integration
+
+### With Architecture Skill
+
+Implements high-level architecture:
+- Takes architectural decisions
+- Maps to concrete components
+- Validates feasibility
+
+### With Integration Skill
+
+Provides boundaries for:
+- API design
+- Service contracts
+- Event schemas
+
+### With wicked-crew
+
+Called during design phase after architecture.
+
+## Events
+
+- `[arch:components:defined:success]` - Components designed
+- `[arch:interface:defined:success]` - Interface documented
+- `[arch:dependency:analyzed:success]` - Dependencies validated
+
+## Tips
+
+1. **Start with Boundaries** - Define what's in/out first
+2. **Think in Interfaces** - Design API before implementation
+3. **Keep It Simple** - Don't over-decompose
+4. **Test Boundaries** - Use contract tests
+5. **Refactor Gradually** - Small, safe steps
+6. **Document Dependencies** - Make them explicit
+
+## Reference Materials
+
+- Component Template:
+  - [Structure & API](refs/component-template-structure.md)
+  - [Lifecycle & Deployment](refs/component-template-lifecycle.md)
+  - [Maintenance & Examples](refs/component-template-maintenance.md)
+- Interface Template:
+  - [Structure & Contracts](refs/interface-template-structure.md)
+  - [Testing & Operations](refs/interface-template-lifecycle.md)
+  - [Examples & Tips](refs/interface-template-maintenance.md)
+- Component Patterns:
+  - [Layered](refs/patterns-layered-pattern.md)
+  - [Plugin Architecture](refs/patterns-plugin-architecture.md)
+  - [Facade](refs/patterns-facade-pattern.md)
+  - [Dependency Injection](refs/patterns-dependency-injection.md)
+- Dependencies:
+  - [Principles](refs/dependencies-dependency-principles.md)
+  - [Tracking](refs/dependencies-dependency-tracking.md)
+  - [Best Practices](refs/dependencies-best-practices.md)
+- Anti-Patterns:
+  - [God Object](refs/anti-patterns-god-object.md)
+  - [Big Ball of Mud](refs/anti-patterns-big-ball-of-mud.md)
+  - [Circular Dependencies](refs/anti-patterns-circular-dependencies.md)
+  - [Feature Envy](refs/anti-patterns-feature-envy.md)

package/skills/engineering/system-design/refs/anti-patterns-big-ball-of-mud.md

@@ -0,0 +1,254 @@
+---
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+# Component Anti-Patterns: Big Ball of Mud
+
+## Big Ball of Mud
+
+### Problem
+
+No clear architecture. Everything coupled to everything.
+
+### Symptoms
+
+```typescript
+// Bad: No structure, everything mixed
+// UserController.ts
+class UserController {
+  async createUser(req, res) {
+    // Validation in controller
+    if (!req.body.email) {
+      return res.status(400).json({ error: 'Email required' });
+    }
+
+    // Database access in controller
+    const existing = await db.query(
+      'SELECT * FROM users WHERE email = $1',
+      [req.body.email]
+    );
+
+    if (existing) {
+      return res.status(409).json({ error: 'Email exists' });
+    }
+
+    // Business logic in controller
+    const hashedPassword = await bcrypt.hash(req.body.password, 10);
+
+    // More database access
+    const result = await db.query(
+      'INSERT INTO users (email, password) VALUES ($1, $2) RETURNING *',
+      [req.body.email, hashedPassword]
+    );
+
+    // Email sending in controller
+    await sendGrid.send({
+      to: req.body.email,
+      subject: 'Welcome',
+      html: '<h1>Welcome!</h1>'
+    });
+
+    // Direct cache access
+    await redis.set(`user:${result.id}`, JSON.stringify(result));
+
+    res.status(201).json(result);
+  }
+}
+```
+
+### Impact
+
+- Impossible to test
+- Can't swap dependencies
+- Violates single responsibility
+- Tightly coupled
+- Hard to maintain
+
+### Solution
+
+Introduce clear layers and separation of concerns:
+
+```typescript
+// Good: Layered architecture
+// Presentation Layer
+class UserController {
+  constructor(private userService: UserService) {}
+
+  async createUser(req: Request, res: Response) {
+    try {
+      const user = await this.userService.createUser(req.body);
+      res.status(201).json(user);
+    } catch (error) {
+      if (error instanceof ValidationError) {
+        res.status(400).json({ error: error.message });
+      } else if (error instanceof ConflictError) {
+        res.status(409).json({ error: error.message });
+      } else {
+        res.status(500).json({ error: 'Internal error' });
+      }
+    }
+  }
+}
+
+// Application Layer
+class UserService {
+  constructor(
+    private userRepo: UserRepository,
+    private emailService: EmailService,
+    private cache: Cache
+  ) {}
+
+  async createUser(data: CreateUserDTO): Promise<User> {
+    // Validation
+    this.validate(data);
+
+    // Check for duplicates
+    const existing = await this.userRepo.findByEmail(data.email);
+    if (existing) {
+      throw new ConflictError('Email already exists');
+    }
+
+    // Create user (domain logic)
+    const user = User.create(data);
+
+    // Persist
+    await this.userRepo.save(user);
+
+    // Send email
+    await this.emailService.sendWelcome(user.email);
+
+    // Cache
+    await this.cache.set(`user:${user.id}`, user);
+
+    return user;
+  }
+
+  private validate(data: CreateUserDTO): void {
+    if (!data.email) {
+      throw new ValidationError('Email required');
+    }
+    if (!data.password || data.password.length < 8) {
+      throw new ValidationError('Password must be at least 8 characters');
+    }
+  }
+}
+
+// Domain Layer
+class User {
+  private constructor(
+    private id: string,
+    private email: string,
+    private passwordHash: string
+  ) {}
+
+  static async create(data: CreateUserDTO): Promise<User> {
+    const hashedPassword = await bcrypt.hash(data.password, 10);
+    return new User(generateId(), data.email, hashedPassword);
+  }
+}
+
+// Infrastructure Layer
+class PostgresUserRepository implements UserRepository {
+  async save(user: User): Promise<void> {
+    await db.query(
+      'INSERT INTO users (id, email, password_hash) VALUES ($1, $2, $3)',
+      [user.id, user.email, user.passwordHash]
+    );
+  }
+
+  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;
+  }
+}
+```
+
+## Leaky Abstraction
+
+### Problem
+
+Implementation details leak through the abstraction.
+
+### Symptoms
+
+```typescript
+// Bad: Leaky abstraction
+interface UserRepository {
+  // SQL query leaking through interface
+  query(sql: string, params: any[]): Promise<any>;
+
+  // Database-specific pagination
+  findAll(offset: number, limit: number): Promise<any>;
+
+  // Redis-specific method
+  flushCache(): Promise<void>;
+}
+
+// Forces consumers to know about SQL
+const users = await userRepo.query(
+  'SELECT * FROM users WHERE email = $1',
+  [email]
+);
+```
+
+### Impact
+
+- Can't swap implementations
+- Tied to specific technology
+- Breaks abstraction principle
+- Hard to test
+
+### Solution
+
+Hide implementation details behind clean interface:
+
+```typescript
+// Good: Clean abstraction
+interface UserRepository {
+  findById(id: string): Promise<User | null>;
+  findByEmail(email: string): Promise<User | null>;
+  findAll(filter?: UserFilter): Promise<User[]>;
+  save(user: User): Promise<void>;
+  delete(id: string): Promise<void>;
+}
+
+interface UserFilter {
+  role?: UserRole;
+  status?: UserStatus;
+  createdAfter?: Date;
+}
+
+// Implementation details hidden
+class PostgresUserRepository implements UserRepository {
+  async findByEmail(email: string): Promise<User | null> {
+    const row = await this.db.query(
+      'SELECT * FROM users WHERE email = $1',
+      [email]
+    );
+    return row ? this.mapToUser(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.mapToUser(row));
+  }
+
+  // Helper methods private
+  private buildQuery(filter?: UserFilter) {
+    // SQL building logic hidden
+  }
+
+  private mapToUser(row: any): User {
+    // Mapping logic hidden
+  }
+}
+
+// Consumer doesn't know about SQL
+const user = await userRepo.findByEmail('test@example.com');
+const activeUsers = await userRepo.findAll({ status: 'active' });
+```
+