runward 0.6.0

package/templates/rules/quality-zod-input-validation.md

@@ -0,0 +1,131 @@
+---
+title: Zod Input Validation
+impact: MEDIUM
+impactDescription: Prevents invalid data from entering the system and provides type safety
+tags: [quality, validation, security, typescript]
+---
+
+## Zod Input Validation
+
+Validate all external inputs with Zod at system boundaries.
+
+**Where to Validate:**
+
+- API endpoints (request body, query params)
+- Environment variables
+- User uploads
+- External API responses
+- Database query results (optional, for defense in depth)
+
+**Incorrect:**
+
+```typescript
+// No validation - trusts external input
+app.post('/api/projects', async (req, res) => {
+  const { name, description, budget } = req.body;  // BAD: Could be anything
+  await db.projects.create({ data: { name, description, budget } });
+});
+
+// Type assertion without validation
+const config = process.env as Config;  // BAD: Not validated
+```
+
+**Correct:**
+
+```typescript
+import { z } from 'zod';
+
+// Define schemas
+const CreateProjectSchema = z.object({
+  name: z.string().min(1).max(100),
+  description: z.string().max(1000).optional(),
+  budget: z.number().positive().optional(),
+  tags: z.array(z.string()).max(10).optional(),
+});
+
+type CreateProjectInput = z.infer<typeof CreateProjectSchema>;
+
+// Validate at API boundary
+app.post('/api/projects', async (req, res) => {
+  // Parse throws ZodError if invalid
+  const input = CreateProjectSchema.parse(req.body);
+
+  // input is now typed and validated
+  await db.projects.create({ data: input });
+});
+
+// Or with safe parsing
+app.post('/api/projects', async (req, res) => {
+  const result = CreateProjectSchema.safeParse(req.body);
+
+  if (!result.success) {
+    return res.status(400).json({
+      error: 'Validation failed',
+      details: result.error.flatten(),
+    });
+  }
+
+  await db.projects.create({ data: result.data });
+});
+```
+
+**Environment Variables:**
+
+```typescript
+// src/lib/env.ts
+const EnvSchema = z.object({
+  DATABASE_URL: z.string().url(),
+  MODEL_API_KEY: z.string().optional(),
+  EMBEDDING_API_KEY: z.string().optional(),
+  PORT: z.coerce.number().default(3000),
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+});
+
+// Validate once at startup
+export const env = EnvSchema.parse(process.env);
+
+// Usage: env.DATABASE_URL is typed and validated
+```
+
+**API Response Validation:**
+
+```typescript
+// Validate external API responses
+const ExternalAPIResponseSchema = z.object({
+  data: z.array(z.object({
+    id: z.string(),
+    name: z.string(),
+    value: z.number(),
+  })),
+  meta: z.object({
+    page: z.number(),
+    total: z.number(),
+  }),
+});
+
+async function fetchExternalData(): Promise<ExternalAPIResponse> {
+  const response = await fetch('https://api.external.com/data');
+  const json = await response.json();
+
+  // Validate response matches expected shape
+  return ExternalAPIResponseSchema.parse(json);
+}
+```
+
+**Error Handling:**
+
+```typescript
+// Middleware for Zod error handling
+function zodErrorHandler(err: Error, req: Request, res: Response, next: NextFunction) {
+  if (err instanceof z.ZodError) {
+    return res.status(400).json({
+      error: 'Validation failed',
+      details: err.errors.map(e => ({
+        path: e.path.join('.'),
+        message: e.message,
+      })),
+    });
+  }
+  next(err);
+}
+```

package/templates/rules/resilience-fail-open.md

@@ -0,0 +1,65 @@
+---
+title: Fail-Open for the Non-Critical, Fail-Closed for the Sensitive
+impact: CRITICAL
+impactDescription: Degrades gracefully where safe and denies safely where it matters, instead of applying one failure policy everywhere
+tags: [resilience, error-handling, availability, safety]
+---
+
+## Fail-Open for the Non-Critical, Fail-Closed for the Sensitive
+
+> **A non-critical service down is not the application down. A sensitive action in doubt is a denied action, never a guessed one.**
+
+The failure policy is not global. You choose it per dependency, by criticality. Getting this split wrong in either direction is a bug: fail-closed on a cache makes you brittle; fail-open on an authorisation makes you unsafe.
+
+**Fail-open (degrade and continue) for reads and the non-critical:**
+
+```typescript
+// Cache failure means slower, not broken.
+async function getCached<T>(key: string): Promise<T | null> {
+  try {
+    return await cache.get<T>(key);
+  } catch (error) {
+    log.error("[CACHE] get failed, continuing without cache", { error });
+    return null;                       // fail-open: continue degraded
+  }
+}
+```
+
+**Fail-closed (deny, explicitly) for the sensitive:**
+
+```typescript
+// Authorisation, the grounding guard, a payment: doubt means deny.
+async function authorise(req: Request): Promise<void> {
+  try {
+    const ok = await authz.check(req);
+    if (!ok) throw new Forbidden();
+  } catch (error) {
+    // Never "allow on error". A guard you fail open is not a guard.
+    throw new Forbidden();             // fail-closed: deny on doubt
+  }
+}
+```
+
+**Suspend, do not block.** Fail-closed does not mean freezing the process. A sensitive action that needs a human serialises the agent's state and rehydrates it on the decision; low-urgency approvals are batched in a prioritised queue. You get the safety of fail-closed without a frozen agent.
+
+**Service classification:**
+
+| Service / action | Policy | On failure |
+|---|---|---|
+| Database (read of record) | Critical | Error to the user |
+| Model call | Critical | Error after retries |
+| Cache | Non-critical | Continue, slower (fail-open) |
+| Audit / analytics logging | Non-critical | Log locally, continue (fail-open) |
+| Optional enrichment (search, memory) | Non-critical | Skip, continue (fail-open) |
+| Authorisation / tenant isolation | Sensitive | Deny (fail-closed) |
+| Grounding / safety guard | Sensitive | Reject the response (fail-closed) |
+| Payment, irreversible write | Sensitive | Abort + require confirmation (fail-closed) |
+
+**The test that tells them apart:** ask "if this dependency is wrong or absent, is the safe answer *continue* or *deny*?" Continue -> fail-open. Deny -> fail-closed. Anything touching safety, authorisation, money, or the truth of a served figure is fail-closed.
+
+**Checklist:**
+
+- [ ] Every external dependency has an explicit failure policy, chosen by criticality.
+- [ ] No safety/authorisation/guard path fails open.
+- [ ] No read-side enrichment fails closed and takes the request down with it.
+- [ ] Fail-closed sensitive actions suspend-and-rehydrate rather than freeze.

package/templates/rules/resilience-multi-provider-fallback.md

@@ -0,0 +1,100 @@
+---
+title: Multi-Provider Fallback
+impact: HIGH
+impactDescription: Ensures LLM availability by falling back to alternative providers
+tags: [resilience, llm, providers, availability]
+---
+
+## Multi-Provider Fallback
+
+Configure fallback providers to handle outages. If primary provider fails, automatically try secondary.
+
+**Model gateway configuration (one option):**
+
+```yaml
+# gateway_config.yaml
+model_list:
+  - model_name: app-fast
+    gateway_params:
+      model: small-fast-model
+    fallbacks:
+      - alt-small-model
+
+  - model_name: app-balanced
+    gateway_params:
+      model: mid-tier-model
+    fallbacks:
+      - alt-mid-model
+
+  - model_name: app-deep
+    gateway_params:
+      model: top-tier-model
+    fallbacks:
+      - alt-mid-model  # No Deep equivalent
+
+router_settings:
+  retry_policy:
+    num_retries: 3
+    backoff_factor: 2
+```
+
+**Manual Fallback (without a model gateway):**
+
+```typescript
+// src/lib/providers/llm-client.ts
+interface LLMClient {
+  complete(request: CompletionRequest): Promise<CompletionResponse>;
+}
+
+const providers: LLMClient[] = [
+  new PrimaryModelClient(),
+  new SecondaryModelClient(),
+  new TertiaryModelClient(),
+];
+
+async function completeWithFallback(
+  request: CompletionRequest
+): Promise<CompletionResponse> {
+  let lastError: Error;
+
+  for (const provider of providers) {
+    try {
+      return await provider.complete(request);
+    } catch (error) {
+      lastError = error as Error;
+      console.warn(`[LLM] Provider failed, trying next:`, {
+        provider: provider.constructor.name,
+        error: lastError.message,
+      });
+    }
+  }
+
+  throw new Error(`All LLM providers failed. Last error: ${lastError!.message}`);
+}
+```
+
+**Provider Priority:**
+
+| Priority | Provider | Notes |
+|----------|----------|-------|
+| 1 | Primary provider | best measured quality |
+| 2 | Secondary provider | availability fallback |
+| 3 | Tertiary provider | last resort |
+| 4 | Local or offline | development, air-gapped |
+
+**When to use each approach:**
+
+- **a model gateway**: Production, complex routing, multiple providers
+- **Manual fallback**: Simple apps, fewer dependencies
+- **Single provider**: Development, prototyping
+
+**Monitoring:**
+
+```typescript
+// Track fallback usage
+console.info('[LLM] Request completed', {
+  primaryProvider: 'primary',
+  usedProvider: response.provider,  // May differ if fallback used
+  fallbackUsed: response.provider !== 'primary',
+});
+```

package/templates/rules/resilience-retry-backoff.md

@@ -0,0 +1,115 @@
+---
+title: LLM Retry with Exponential Backoff
+impact: HIGH
+impactDescription: Handles transient LLM failures gracefully without overwhelming the API
+tags: [resilience, llm, retry, error-handling]
+---
+
+## LLM Retry with Exponential Backoff
+
+LLM APIs experience rate limits and transient errors. Implement retry with exponential backoff.
+
+**Incorrect:**
+
+```typescript
+// No retry - single failure = user error
+const response = await model.complete({...});
+
+// Or: immediate retry flood
+while (retries < 3) {
+  try {
+    return await model.complete({...});
+  } catch {
+    retries++;  // BAD: No delay
+  }
+}
+```
+
+**Correct:**
+
+```typescript
+// src/lib/resilience/retry.ts
+interface RetryConfig {
+  maxRetries: number;
+  initialDelayMs: number;
+  maxDelayMs: number;
+  retryableErrors: string[];
+}
+
+const defaultConfig: RetryConfig = {
+  maxRetries: 3,
+  initialDelayMs: 1000,
+  maxDelayMs: 10000,
+  retryableErrors: ['rate_limit_error', 'overloaded_error', 'api_error'],
+};
+
+function isRetryable(error: unknown, retryableErrors: string[]): boolean {
+  if (error instanceof Error) {
+    return retryableErrors.some(e => error.message.includes(e));
+  }
+  return false;
+}
+
+async function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+export async function withLLMRetry<T>(
+  fn: () => Promise<T>,
+  config = defaultConfig
+): Promise<T> {
+  let lastError: Error;
+
+  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error as Error;
+
+      // Don't retry non-retryable errors
+      if (!isRetryable(error, config.retryableErrors)) {
+        throw error;
+      }
+
+      // Don't delay after last attempt
+      if (attempt < config.maxRetries) {
+        const delay = Math.min(
+          config.initialDelayMs * Math.pow(2, attempt),
+          config.maxDelayMs
+        );
+        console.warn(`[LLM] Retry ${attempt + 1}/${config.maxRetries} after ${delay}ms`, {
+          error: lastError.message,
+        });
+        await sleep(delay);
+      }
+    }
+  }
+
+  throw lastError!;
+}
+
+// Usage
+const response = await withLLMRetry(() =>
+  model.complete({
+    model: 'mid-tier-model',
+    messages,
+  })
+);
+```
+
+**Retry Delays:**
+
+| Attempt | Delay | Total Wait |
+|---------|-------|------------|
+| 1 | 1000ms | 1s |
+| 2 | 2000ms | 3s |
+| 3 | 4000ms | 7s |
+
+**Retryable vs Non-Retryable:**
+
+| Retryable | Non-Retryable |
+|-----------|---------------|
+| `rate_limit_error` | `invalid_request_error` |
+| `overloaded_error` | `authentication_error` |
+| `api_error` | `invalid_api_key` |
+| Network timeouts | Validation errors |

package/templates/rules/resilience-retryable-errors.md

@@ -0,0 +1,107 @@
+---
+title: Retryable vs Non-Retryable Errors
+impact: MEDIUM
+impactDescription: Prevents wasted retries and ensures quick failure for unrecoverable errors
+tags: [resilience, error-handling, llm]
+---
+
+## Retryable vs Non-Retryable Errors
+
+Not all errors should be retried. Distinguishing them prevents wasted time and API calls.
+
+**Error Classification:**
+
+| Retryable (transient) | Non-Retryable (permanent) |
+|----------------------|---------------------------|
+| `rate_limit_error` | `invalid_request_error` |
+| `overloaded_error` | `authentication_error` |
+| `api_error` (500s) | `invalid_api_key` |
+| Network timeout | `model_not_found` |
+| Connection reset | Validation errors |
+| `service_unavailable` | `content_policy_violation` |
+
+**Incorrect:**
+
+```typescript
+// Retries everything, including permanent errors
+async function callLLM(request: Request): Promise<Response> {
+  for (let i = 0; i < 3; i++) {
+    try {
+      return await model.complete(request);
+    } catch (error) {
+      await sleep(1000 * Math.pow(2, i));  // BAD: Retries invalid_api_key
+    }
+  }
+  throw new Error('Failed after retries');
+}
+```
+
+**Correct:**
+
+```typescript
+const RETRYABLE_ERRORS = new Set([
+  'rate_limit_error',
+  'overloaded_error',
+  'api_error',
+  'service_unavailable',
+  'ECONNRESET',
+  'ETIMEDOUT',
+  'ENOTFOUND',
+]);
+
+function isRetryable(error: unknown): boolean {
+  if (error instanceof ModelAPIError) {
+    // provider SDK specific
+    if (error.status === 429) return true;  // Rate limit
+    if (error.status >= 500) return true;   // Server error
+    return false;  // Client errors (4xx except 429)
+  }
+
+  if (error instanceof Error) {
+    // Network errors
+    return RETRYABLE_ERRORS.has(error.name) ||
+           RETRYABLE_ERRORS.has((error as any).code);
+  }
+
+  return false;
+}
+
+async function callLLM(request: Request): Promise<Response> {
+  let lastError: Error;
+
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try {
+      return await model.complete(request);
+    } catch (error) {
+      lastError = error as Error;
+
+      // Fail fast on permanent errors
+      if (!isRetryable(error)) {
+        console.error('[LLM] Non-retryable error:', error);
+        throw error;
+      }
+
+      // Retry with backoff for transient errors
+      const delay = Math.min(1000 * Math.pow(2, attempt), 10000);
+      console.warn(`[LLM] Retryable error, waiting ${delay}ms:`, error);
+      await sleep(delay);
+    }
+  }
+
+  throw lastError!;
+}
+```
+
+**HTTP Status Code Guide:**
+
+| Status | Meaning | Retry? |
+|--------|---------|--------|
+| 400 | Bad Request | No |
+| 401 | Unauthorized | No |
+| 403 | Forbidden | No |
+| 404 | Not Found | No |
+| 429 | Rate Limited | **Yes** |
+| 500 | Server Error | **Yes** |
+| 502 | Bad Gateway | **Yes** |
+| 503 | Unavailable | **Yes** |
+| 504 | Timeout | **Yes** |

package/templates/rules/routing-confidence-upgrade.md

@@ -0,0 +1,89 @@
+---
+title: If Doubt, Upgrade the Model
+impact: CRITICAL
+impactDescription: Prevents quality degradation from incorrect model selection
+tags: [routing, llm, cost-optimization, quality]
+---
+
+## If Doubt, Upgrade the Model
+
+When the complexity classifier isn't confident, always upgrade to a more capable model. The cost of a wrong downgrade (poor response) exceeds the cost of unnecessary upgrade.
+
+**The Rule:**
+
+> **CRITICAL: If confidence < 0.6, ALWAYS upgrade to the next tier.**
+
+**Incorrect:**
+
+```typescript
+// Uses lower model even when uncertain
+function selectModel(complexity: ComplexityResult): Model {
+  switch (complexity.level) {
+    case 'casual': return 'fast';
+    case 'task': return 'balanced';
+    case 'deep': return 'deep';
+  }
+  // BAD: No confidence check - may misroute
+}
+```
+
+**Correct:**
+
+```typescript
+interface ComplexityResult {
+  level: 'casual' | 'task' | 'planning' | 'deep';
+  confidence: number;  // 0-1
+}
+
+function selectModel(complexity: ComplexityResult): Model {
+  const { level, confidence } = complexity;
+
+  // If confidence is low, upgrade to be safe
+  if (confidence < 0.6) {
+    console.info(`[ROUTING] Low confidence (${confidence}), upgrading from ${level}`);
+    return upgradeModel(level);
+  }
+
+  switch (level) {
+    case 'casual': return 'fast';
+    case 'task':
+    case 'planning': return 'balanced';
+    case 'deep': return 'deep';
+  }
+}
+
+function upgradeModel(level: string): Model {
+  switch (level) {
+    case 'casual': return 'balanced';   // fast → balanced
+    case 'task': return 'balanced';     // stay balanced
+    case 'planning': return 'deep';   // balanced → deep
+    case 'deep': return 'deep';       // stay deep
+    default: return 'balanced';         // safe default
+  }
+}
+```
+
+**Cost Analysis:**
+
+| Scenario | Model | Cost | Quality Risk |
+|----------|-------|------|--------------|
+| Confident casual → Fast | $0.005 | Low |
+| Uncertain casual → Fast | $0.005 | **HIGH** (wrong model) |
+| Uncertain casual → Balanced | $0.025 | Low |
+
+**The Math:**
+
+- Wrong model = user frustration + retry = 2x cost minimum
+- Upgrade cost = 5x base (Balanced vs Fast)
+- But: upgrade only when uncertain (~30% of cases)
+- Net: slight cost increase, major quality improvement
+
+**Detection Flow:**
+
+```
+Message → detectWithRegex() → confidence ≥ 0.6?
+    ├─ YES → Use regex result
+    └─ NO → detectWithFastModel() → confidence ≥ 0.6?
+              ├─ YES → Use Fast result
+              └─ NO → UPGRADE MODEL
+```

package/templates/rules/routing-model-cost-ratios.md

@@ -0,0 +1,68 @@
+---
+title: Model Cost Ratios
+impact: HIGH
+impactDescription: Essential reference for cost optimization decisions
+tags: [routing, llm, cost-optimization, reference]
+---
+
+## Model Cost Ratios
+
+Understanding cost ratios is essential for routing decisions.
+
+**Cost ratios (illustrative orders of magnitude, verify current vendor prices):**
+
+| Model | Input ($/M tokens) | Output ($/M tokens) | Ratio vs Balanced |
+|-------|-------------------|---------------------|-----------------|
+| Fast | $0.25 | $1.25 | **0.08x** |
+| Balanced | $3.00 | $15.00 | 1.0x |
+| Deep | $15.00 | $75.00 | 5.0x |
+
+**Cost per typical request:**
+
+| Model | Typical Request Cost | Use Case |
+|-------|---------------------|----------|
+| Fast | ~$0.005 | Greetings, simple Q&A, confirmations |
+| Balanced | ~$0.025 | Standard tasks, analysis, coding |
+| Deep | ~$0.10 | Complex reasoning, architecture, deep analysis |
+
+**Key Insight:**
+
+> Fast is **12x cheaper** than Balanced.
+> Using Fast for 25% of traffic saves ~$0.015/request average.
+
+**Incorrect:**
+
+```typescript
+// No cost awareness
+const model = 'mid-tier-model';  // Always mid-tier
+```
+
+**Correct:**
+
+```typescript
+const MODEL_COSTS = {
+  'small-fast-model': { input: 0.25, output: 1.25 },
+  'mid-tier-model': { input: 3.00, output: 15.00 },
+  'top-tier-model': { input: 15.00, output: 75.00 },
+} as const;
+
+function estimateCost(model: string, inputTokens: number, outputTokens: number): number {
+  const costs = MODEL_COSTS[model];
+  return (inputTokens * costs.input + outputTokens * costs.output) / 1_000_000;
+}
+
+// Log costs for monitoring
+console.info('[LLM] Request completed', {
+  model,
+  inputTokens: response.usage.input_tokens,
+  outputTokens: response.usage.output_tokens,
+  estimatedCost: estimateCost(model, response.usage.input_tokens, response.usage.output_tokens),
+});
+```
+
+**Cost Optimization Levers:**
+
+1. **Smart routing** → Use Fast when possible (-40% average)
+2. **Cache optimization** → Reduce input tokens (-60% on cached)
+3. **Output limits** → Constrain max_tokens where appropriate
+4. **Prompt engineering** → Shorter prompts, same quality