wicked-garden 12.27.0

package/skills/engineering/patch/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: patch
+description: |
+  Language-agnostic code generation and change propagation. Use this skill when
+  adding fields to entities, renaming symbols across files, or propagating changes
+  that affect multiple files. Use when: "add field", "rename everywhere",
+  "propagate change", "generate migration", "update all references".
+
+  This is the CODE MUTATION counterpart to wicked-garden:search (which is read-only).
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+
+# wicked-patch
+
+Generate and propagate code changes across your entire codebase using the symbol graph.
+
+## Quick Start
+
+```bash
+# 1. Index your codebase (if not already done)
+/wicked-garden:search:index /path/to/project
+
+# 2. Add a field to an entity
+/wicked-garden:engineering:add-field "Entity.java::User" --name email --type String
+
+# 3. Rename a field everywhere
+/wicked-garden:engineering:rename "Entity.java::User" --old status --new state
+
+# 4. See propagation plan
+/wicked-garden:engineering:plan "Entity.java::User" --change add_field
+```
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/wicked-garden:engineering:plan` | Show what would be affected |
+| `/wicked-garden:engineering:add-field` | Add field with propagation |
+| `/wicked-garden:engineering:rename` | Rename across all usages |
+| `/wicked-garden:engineering:remove` | Remove field everywhere |
+| `/wicked-garden:engineering:apply` | Apply saved patches |
+
+## Supported Languages
+
+| Extension | Features |
+|-----------|----------|
+| `.java` | JPA @Column, getters/setters, validation |
+| `.py` | SQLAlchemy, Pydantic, dataclass |
+| `.ts`, `.js` | TypeORM, interfaces, types |
+| `.jsp` | Spring form tags, EL expressions |
+| `.sql` | ALTER TABLE (PostgreSQL, Oracle, MySQL, SQL Server) |
+
+## How It Works
+
+```
+ChangeSpec (add field "email" to User)
+           │
+           ▼
+   ┌───────────────────┐
+   │ Propagation Engine │  ← Uses wicked-garden:search lineage graph
+   └───────────────────┘
+           │
+    ┌──────┼──────┬──────────┐
+    ▼      ▼      ▼          ▼
+  Java   Python   SQL      JSP
+   │       │       │         │
+   ▼       ▼       ▼         ▼
+Patches  Patches Patches  Patches
+```
+
+## Examples
+
+### Add Field to JPA Entity
+
+```bash
+/wicked-garden:engineering:add-field "User.java::User" \
+  --name email \
+  --type String \
+  --column USER_EMAIL \
+  --required
+```
+
+**Generates:**
+
+```java
+// User.java
+@Column(name = "USER_EMAIL")
+@NotNull
+private String email;
+
+public String getEmail() { return this.email; }
+public void setEmail(String email) { this.email = email; }
+```
+
+```sql
+-- migration.sql
+ALTER TABLE USERS ADD COLUMN USER_EMAIL VARCHAR(255) NOT NULL;
+```
+
+### Rename Field Everywhere
+
+```bash
+/wicked-garden:engineering:rename "Order.java::Order" --old status --new orderStatus
+```
+
+**Updates:**
+- Entity field declaration
+- Getters/setters
+- JSP form bindings (`${order.status}` → `${order.orderStatus}`)
+- Service layer references
+- Test files (with warning)
+
+### Save and Review Patches
+
+```bash
+# Generate patches without applying
+/wicked-garden:engineering:add-field SYMBOL --name foo --type String --output patches.json
+
+# Review the patches file
+cat patches.json
+
+# Apply when ready
+/wicked-garden:engineering:apply patches.json
+```
+
+## Type Mappings
+
+Generic types are automatically mapped per language:
+
+| Generic | Java | Python | TypeScript | SQL |
+|---------|------|--------|------------|-----|
+| `string` | String | str | string | VARCHAR(255) |
+| `integer` | Integer | int | number | INTEGER |
+| `boolean` | boolean | bool | boolean | BOOLEAN |
+| `date` | LocalDate | date | Date | DATE |
+| `datetime` | LocalDateTime | datetime | Date | TIMESTAMP |
+| `decimal` | BigDecimal | Decimal | number | DECIMAL(18,2) |
+
+## SQL Dialect Support
+
+Auto-detected or specify via `--dialect`:
+
+```sql
+-- PostgreSQL (default)
+ALTER TABLE users ADD COLUMN email VARCHAR(255);
+
+-- Oracle
+ALTER TABLE users ADD (email VARCHAR2(255));
+
+-- MySQL
+ALTER TABLE users ADD COLUMN email VARCHAR(255);
+
+-- SQL Server
+ALTER TABLE users ADD email NVARCHAR(255);
+```
+
+## Integration with wicked-garden:search
+
+wicked-patch reads from the wicked-garden:search symbol database:
+
+```bash
+# 1. wicked-garden:search creates the graph
+/wicked-garden:search:index /project --derive-all
+
+# 2. wicked-patch uses it for propagation
+/wicked-garden:engineering:add-field SYMBOL --name foo --type String
+```
+
+## Safety Features
+
+- **Dry-run by default**: Shows patches without applying
+- **Confirmation prompt**: Asks before applying
+- **Patch files**: Save for review before applying
+- **Warnings**: Highlights test files and unsupported types
+- **Reversible**: Use git to undo
+
+## CLI Reference
+
+```bash
+cd "${CLAUDE_PLUGIN_ROOT}/scripts"
+sh "${CLAUDE_PLUGIN_ROOT}/scripts/_python.sh" "${CLAUDE_PLUGIN_ROOT}/scripts/patch.py" --help
+sh "${CLAUDE_PLUGIN_ROOT}/scripts/_python.sh" "${CLAUDE_PLUGIN_ROOT}/scripts/patch.py" generators  # List supported languages
+```

package/skills/engineering/refs/arch.md

@@ -0,0 +1,126 @@
+# arch — architecture analysis rubric
+
+Full checklist and output format for architecture review at module/service/system scope.
+Use `engineering:arch` for component/system-level review; use `engineering:review` for code-level review.
+
+## Scope routing
+
+- `--scope module` or `--scope service`: evaluate component boundaries and responsibilities
+- `--scope system`: evaluate decomposition, communication patterns, and data architecture
+- Infer from context if absent (single directory = module; multiple services = system)
+
+## Module / service analysis checklist
+
+### Boundaries and responsibilities
+- [ ] Component responsibility is clearly scoped (single reason to change)
+- [ ] No responsibility bleed — one component isn't doing another's job
+- [ ] Interface contracts explicit: public API vs internals clearly separated
+- [ ] Information hiding: internal implementation not exposed through boundaries
+
+### Coupling and cohesion
+- [ ] High cohesion — related things grouped together
+- [ ] Low coupling — minimal dependencies on other components
+- [ ] Coupling type: prefer Data > Message > no coupling; avoid Common/Content coupling
+- [ ] No circular dependencies; clear dependency direction
+
+### Dependency management
+- [ ] Dependencies declared, not implicit
+- [ ] No version mismatches or conflicting transitive deps
+- [ ] Abstraction layers used to isolate external dependencies
+
+### If reviewing a diff
+- [ ] No unauthorized new boundaries added without approval
+- [ ] No communication pattern changes (sync→async, REST→event) without ADR
+- [ ] No new external dependencies added outside change scope
+- [ ] No scope creep ("while I'm here" restructuring)
+
+### Output format — module/service
+
+```markdown
+## Architecture Review: {name} (module/service)
+
+### Strengths
+- {strength with evidence}
+
+### Concerns
+
+| Severity | Concern | Location | Recommendation |
+|----------|---------|----------|----------------|
+| HIGH/MED/LOW | {concern} | `{file or component}` | {action} |
+
+### Recommendations
+1. {primary with rationale}
+2. {secondary}
+
+### Trade-off Table
+| Option | Pros | Cons |
+|--------|------|------|
+```
+
+## System analysis checklist
+
+### Decomposition
+- [ ] Service boundaries align with domain/team ownership
+- [ ] Each service independently deployable and rollback-able
+- [ ] Services not chatty (many synchronous calls = consider merge or BFF)
+- [ ] No distributed monolith (services coupled by shared DB or step-lock deployments)
+
+### Communication patterns
+- [ ] Sync (REST/gRPC) vs async (events/queue) chosen deliberately per use case
+- [ ] Event contracts versioned and documented
+- [ ] Circuit breakers and timeouts on all sync calls
+- [ ] Idempotency for all async consumers
+
+### Data architecture
+- [ ] Each service owns its data — no shared DB across service boundaries
+- [ ] Data residency and replication strategy documented
+- [ ] CQRS / event sourcing used only where justified, not default
+- [ ] Eventual consistency acknowledged where applicable
+
+### Scalability and operations
+- [ ] Stateless services where possible (state in DB/cache, not local)
+- [ ] Horizontal scaling possible for each service
+- [ ] Observability: each service emits structured logs, metrics, traces
+- [ ] Failure modes documented: what degrades gracefully vs fails hard
+
+### If reviewing a diff
+- [ ] No new inter-service synchronous dependencies added
+- [ ] No shared state introduced across service boundaries
+- [ ] No scope creep beyond the stated system change
+
+### Output format — system
+
+```markdown
+## Architecture Review: {name} (system)
+
+### Overview
+{one paragraph system description}
+
+### Strengths
+- {strength}
+
+### Concerns
+
+| Severity | Concern | Service/Component | Recommendation |
+|----------|---------|-------------------|----------------|
+| HIGH/MED/LOW | {concern} | {target} | {action} |
+
+### Strategic Recommendations
+1. {primary — long-term direction}
+2. {secondary}
+
+### Trade-off Table
+| Decision | Current | Alternative | When to revisit |
+|----------|---------|-------------|-----------------|
+
+### ADR Candidates
+- {decision worth recording as an ADR}
+```
+
+## Architecture principles (apply to both scopes)
+
+- **SOLID**: Single responsibility, open/closed, Liskov, interface segregation, dependency inversion
+- **DRY** (applied judiciously): don't force DRY across unrelated domains
+- **YAGNI**: flag speculative generality — build for now, not speculation
+- **Least Privilege**: minimal permissions and surface area
+- **Fail-fast over silent corruption**: errors should surface immediately, not propagate silently

package/skills/engineering/refs/debug.md

@@ -0,0 +1,142 @@
+# debug — garden-specific debug rubric
+
+Wicked-garden preferred debug process. For the full systematic methodology, invoke
+`superpowers:systematic-debugging` which covers hypothesis-driven debugging in depth.
+This ref captures garden-specific heuristics and the standard output format.
+
+## Garden-specific debug heuristics
+
+### 1. Check the bus first (wicked-bus events)
+
+Most garden failures surface as missing or malformed events. Before reading code:
+```bash
+wicked-bus query --limit 20 --format json   # recent events
+wicked-bus query --event "domain:*:failed"  # failure events
+```
+
+### 2. Check wicked-loom / wicked-vault availability
+
+Gate failures that say `"gate: unavailable"` are almost always a loom/vault resolution issue, not a logic bug:
+- Is `WICKED_LOOM_BIN` set correctly?
+- Is `wicked-vault` available via `npx`?
+- Is `WICKED_LOOM_CUTOVER=off` accidentally set?
+
+### 3. Hook scripts: always run with `python3 -c "..."` test first
+
+Hook issues are commonly cross-platform JSON output failures. Test the hook script standalone:
+```bash
+python3 scripts/hooks/script.py '{"event": "test"}' 2>&1
+```
+
+### 4. Scope creep as a bug category
+
+When reviewing a diff that triggers a bug report, check if the diff contains changes *outside* the stated scope — scope creep often introduces subtle regressions.
+
+## Six-step debugging process
+
+1. **Understand** — expected vs actual behavior, reproduction steps, when it started
+2. **Gather evidence** — logs, stack traces, recent changes, config drift
+3. **Form hypothesis** — most likely cause + what would disprove it
+4. **Test hypothesis** — targeted test, not random changes
+5. **Implement fix** — minimal fix, verify resolution, add regression test
+6. **Document** — root cause, fix rationale, prevention measure
+
+## Issue categories
+
+| Category | Examples |
+|----------|---------|
+| Logic errors | Wrong conditions, off-by-one, missing edge cases |
+| State errors | Race conditions, stale closures, shared mutable state |
+| Integration errors | API contract mismatch, auth failures, timeout, format mismatch |
+| Performance | N+1 queries, missing indexes, memory leaks, unbounded loops |
+| Environment | Config differences, missing env vars, version mismatches, permissions |
+| Garden-specific | Loom unavailable, vault unresolvable, bus consumer not registered, hook cross-platform failure |
+
+## Standard output format
+
+```markdown
+## Debug Analysis: {issue title}
+
+### Symptom
+{what was observed — exact error message or behavior}
+
+### Root Cause
+{underlying issue — not just the symptom}
+
+**Confidence**: HIGH / MEDIUM / LOW
+
+### Why This Happened
+{explain the causal chain from trigger to symptom}
+
+### Evidence
+- `{file}:{line}` — {what was found}
+- {log entry or test result}
+
+### Reproduction Steps
+1. {step}
+2. {step}
+3. Observe: {expected} vs {actual}
+
+### Recommended Fix
+
+```diff
+- {bad code}
++ {fixed code}
+```
+
+**Rationale**: {why this fixes the root cause, not just the symptom}
+
+### Verification
+1. {how to verify the fix works}
+2. {what to monitor after deploying}
+
+### Prevention
+- {test to add}
+- {monitoring/alerting to add}
+- {code pattern to avoid}
+
+### Alternative Explanations
+{only if confidence is not HIGH — other possible causes}
+```
+
+## Debugging techniques
+
+### Stack trace analysis — work backwards
+
+```
+Error: Cannot read property 'id' of undefined
+  at getUserName (user.js:42)   ← What is undefined here?
+  at renderProfile (profile.js:15)  ← What data was passed?
+  at App.render (App.js:88)   ← Where did this come from?
+```
+
+### Binary search with git bisect
+
+```bash
+git bisect start
+git bisect bad HEAD
+git bisect good v1.2.0
+# test each commit git bisect suggests
+```
+
+### Async timing issues — common pattern
+
+```javascript
+// Bug: result is undefined — await missing
+let result;
+fetchData().then(data => result = data);
+console.log(result);  // undefined!
+
+// Fix
+const result = await fetchData();
+```
+
+### Null/undefined — prefer optional chaining
+
+```javascript
+// Bug
+user.profile.name  // profile might be null
+
+// Fix
+user?.profile?.name ?? 'Unknown'
+```

package/skills/engineering/refs/docs.md

@@ -0,0 +1,190 @@
+# docs — documentation generation rubric
+
+Checklist, output templates, and quality standards for generating API docs, READMEs,
+guides, and inline comments. API/reference docs route to the `api-documentarian` agent;
+narrative docs (READMEs, guides, comments) are generated inline with this rubric.
+
+## Documentation type routing
+
+| `--type` | What to generate | Primary audience |
+|----------|-----------------|-----------------|
+| `api` | OpenAPI spec + endpoint reference | Integrating developers |
+| `readme` | Project/component README | New users, contributors |
+| `guide` | How-to tutorial for a specific task | Practitioners |
+| `inline` | Code comments and docstrings | Code readers |
+
+Infer if absent: `.ts/.py/.go` file → api or inline; top-level dir → readme; workflow request → guide.
+
+## Pre-generation checklist (read the code first)
+
+- [ ] Read all public interfaces and exports
+- [ ] Read all function signatures, parameters, return types
+- [ ] Read error conditions and what triggers them
+- [ ] Read existing docs for drift (what's changed from docs vs code)
+- [ ] Identify audience: who will read this?
+
+## API documentation checklist (OpenAPI-first)
+
+### Required per endpoint/function
+- [ ] Summary (one line) and description (what, when to use, what not to use)
+- [ ] All parameters: name, location, type, required/optional, description, example
+- [ ] All response codes: 2xx success schema + example, 4xx client errors, 5xx server errors
+- [ ] Authentication requirements stated explicitly
+- [ ] Operation ID assigned (for SDK generation)
+- [ ] At least one working request example (bash curl or language snippet)
+
+### Schema documentation
+- [ ] Required vs optional fields marked
+- [ ] Types accurate (format: email, date-time, uuid, etc.)
+- [ ] Descriptions for each field (not just the type)
+- [ ] Constraints: min/max, pattern, enum values
+- [ ] Example values provided
+
+### OpenAPI quality bar
+- [ ] Valid OpenAPI 3.0+ syntax
+- [ ] All `$ref` targets exist
+- [ ] Examples match schemas they illustrate
+- [ ] Consistent naming: operations as verbs (getUser), paths lowercase-kebab, schemas PascalCase
+- [ ] Deprecations documented with `Deprecation` header and `Sunset` date
+
+### API output template
+
+```yaml
+openapi: 3.0.0
+info:
+  title: {Component} API
+  version: {version}
+  description: |
+    {What this API does}. Base URL: {base_url}
+
+paths:
+  /{resource}/{id}:
+    get:
+      summary: {one-line description}
+      operationId: {camelCaseVerb}
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: {what it identifies}
+      responses:
+        '200':
+          description: {success description}
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/{Resource}'
+              example:
+                {field}: {value}
+        '404':
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+      security:
+        - bearerAuth: []
+
+components:
+  schemas:
+    {Resource}:
+      type: object
+      required: [{required_fields}]
+      properties:
+        id:
+          type: string
+          description: Unique identifier
+    Error:
+      type: object
+      properties:
+        error: {type: string}
+        message: {type: string}
+        code: {type: string}
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+```
+
+## README checklist
+
+- [ ] What — one to two sentence description
+- [ ] Why — what problem does this solve
+- [ ] How — working quick-start example (tested)
+- [ ] Where — links to detailed docs
+- [ ] Keep under 300 lines; link to `/docs` for details
+- [ ] Installation step-by-step
+- [ ] Configuration options table (if applicable)
+- [ ] Badge: CI status (optional but helpful)
+
+### README template
+
+```markdown
+# {Component Name}
+
+{One sentence description of what this does and why it exists.}
+
+## Installation
+
+{Step-by-step, tested}
+
+## Quick Start
+
+```{language}
+{simplest working example}
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+
+## API
+
+{Key functions/endpoints — link to full API docs}
+
+## Contributing
+
+{Link to CONTRIBUTING.md or brief notes}
+```
+
+## How-to guide checklist
+
+- [ ] Goal stated upfront (what you'll accomplish)
+- [ ] Prerequisites listed (knowledge + tools needed)
+- [ ] Steps numbered, tested, include expected output
+- [ ] Result shown (what success looks like)
+- [ ] Troubleshooting section for common failure modes
+- [ ] Active voice throughout ("Run the command" not "The command should be run")
+- [ ] Code examples before explanation (show, then tell)
+
+## Inline comments checklist
+
+- [ ] Comments explain WHY, not WHAT (the code shows what)
+- [ ] Non-obvious algorithms or heuristics documented
+- [ ] Docstrings: all public functions have summary + params + return + raises
+- [ ] TODO/FIXME comments have an issue reference or an owner
+- [ ] No commented-out code (delete it or track via issue)
+
+## Writing quality standards
+
+**Active voice**: "Run the command" not "The command should be run"
+**Concise**: strip filler ("In order to" → "To")
+**Example-first**: code block before prose explanation
+**Consistent terminology**: pick one name per concept and stick to it
+**Scannable**: headers, bullets, short paragraphs — most readers skim first
+
+## Output locations
+
+| Type | Write to |
+|------|---------|
+| OpenAPI spec | `docs/api/openapi.yaml` or alongside code |
+| Endpoint reference | `docs/api/{resource}.md` |
+| README | component root `README.md` |
+| Guides | `docs/guides/{topic}.md` |
+| Inline | use Edit tool in-file |
+
+Always present for user review before writing to file.