runward 0.6.0

package/templates/rules/patterns-memory-router-tiered.md

@@ -0,0 +1,139 @@
+---
+title: Tiered Memory Router
+impact: HIGH
+impactDescription: Order-of-magnitude latency cut on simple queries by fetching only the memory tier the query needs, measured on a reference system — recalibrate on your traffic
+tags: [patterns, memory, performance, architecture]
+---
+
+## Tiered Memory Router
+
+Not every query needs full memory search. Route to appropriate tier based on complexity.
+
+**The Problem:**
+
+Fetching all memory sources for every query:
+- Slow (full graph traversal, vector search)
+- Expensive (embedding generation)
+- Unnecessary for simple queries
+
+**Tiered Approach:**
+
+```
+Tier 0 (casual) - ~50ms
+└── Presence, timezone, basic stats only
+
+Tier 1 (task) - ~400ms
+└── Tier 0 + vector search + recent memories
+
+Tier 2 (deep) - ~1200ms
+└── Tier 0 + Tier 1 + graph traversal + archival search
+```
+
+**Incorrect:**
+
+```typescript
+// Always fetch everything
+async function getContext(userId: string, query: string): Promise<Context> {
+  const [presence, memories, graph, archives] = await Promise.all([
+    getPresence(userId),
+    searchMemories(query),          // BAD: Always runs
+    traverseGraph(userId, query),   // BAD: Always runs
+    searchArchives(query),          // BAD: Always runs
+  ]);
+  return { presence, memories, graph, archives };
+}
+```
+
+**Correct:**
+
+```typescript
+type MemoryTier = 0 | 1 | 2;
+
+interface MemoryRouterConfig {
+  tier: MemoryTier;
+  sources: MemorySource[];
+  timeout: number;
+}
+
+const tierConfigs: Record<MemoryTier, MemoryRouterConfig> = {
+  0: {
+    tier: 0,
+    sources: ['presence', 'basicStats'],
+    timeout: 100,
+  },
+  1: {
+    tier: 1,
+    sources: ['presence', 'basicStats', 'vectorSearch', 'recentMemories'],
+    timeout: 500,
+  },
+  2: {
+    tier: 2,
+    sources: ['presence', 'basicStats', 'vectorSearch', 'recentMemories', 'graphTraversal', 'archivalSearch'],
+    timeout: 2000,
+  },
+};
+
+function selectTier(complexity: ComplexityLevel): MemoryTier {
+  switch (complexity) {
+    case 'casual': return 0;
+    case 'task': return 1;
+    case 'planning':
+    case 'deep': return 2;
+  }
+}
+
+async function getContext(
+  userId: string,
+  query: string,
+  complexity: ComplexityLevel
+): Promise<Context> {
+  const tier = selectTier(complexity);
+  const config = tierConfigs[tier];
+
+  const fetchers: Record<MemorySource, () => Promise<any>> = {
+    presence: () => getPresence(userId),
+    basicStats: () => getBasicStats(userId),
+    vectorSearch: () => searchMemories(query),
+    recentMemories: () => getRecentMemories(userId),
+    graphTraversal: () => traverseGraph(userId, query),
+    archivalSearch: () => searchArchives(query),
+  };
+
+  // Per-source timeout with allSettled: one slow source degrades only
+  // itself. A global Promise.race that resolves to [] on timeout would
+  // throw away everything — including sources that had already answered.
+  const settled = await Promise.allSettled(
+    config.sources.map(source => withTimeout(fetchers[source](), config.timeout))
+  );
+
+  const results = settled
+    .filter((r): r is PromiseFulfilledResult<unknown> => r.status === 'fulfilled')
+    .map(r => r.value);
+
+  const failed = settled.length - results.length;
+  if (failed > 0) {
+    console.warn(`[MEMORY] Tier ${tier}: ${failed}/${settled.length} sources failed or timed out, degrading`);
+  }
+
+  return buildContext(results);
+}
+
+function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  return Promise.race([
+    promise,
+    sleep(ms).then(() => Promise.reject(new Error('memory source timeout'))),
+  ]);
+}
+```
+
+Tier 0 sources (`presence`, `basicStats`) are part of every tier's source list and are cheap key-value reads: a degraded response still carries them. If you need a hard guarantee, await them separately from the optional sources so they are never dropped.
+
+**Latency Impact (measured on a reference system — recalibrate on your traffic):**
+
+| Query Type | Old (all sources) | New (tiered) | Savings |
+|------------|-------------------|--------------|---------|
+| "Hi" | 1200ms | 50ms | **96%** |
+| "Summarize project" | 1200ms | 400ms | **67%** |
+| "Analyze market trends" | 1200ms | 1200ms | 0% |
+
+Average latency reduction is large — an order of magnitude on simple queries — but the weighted figure depends entirely on your traffic distribution. The numbers above come from one reference system; measure your own before quoting a percentage.

package/templates/rules/patterns-prompt-compiler.md

@@ -0,0 +1,126 @@
+---
+title: Prompt as Program (Prompt Compiler)
+impact: MEDIUM
+impactDescription: Enables versioning, testing, and optimization of prompts
+tags: [patterns, prompts, llm, architecture]
+---
+
+## Prompt as Program (Prompt Compiler)
+
+Treat prompts as compiled programs, not raw strings. This enables versioning, testing, and optimization.
+
+**Incorrect:**
+
+```typescript
+// Raw string concatenation
+const prompt = `
+You are an assistant.
+${userContext}
+${projectInfo}
+${tools.map(t => t.description).join('\n')}
+${userMessage}
+`;
+```
+
+**Correct:**
+
+```typescript
+// Prompt as structured data
+interface CompiledPrompt {
+  content: string;
+  tokenEstimate: number;
+  cacheKey: string;
+  locale: Locale;
+  cacheLevel: 'L1' | 'L2' | 'L3';
+  blocks: PromptBlock[];
+  version: string;
+}
+
+interface PromptBlock {
+  name: string;
+  content: string;
+  tokens: number;
+  cacheLevel: 'L1' | 'L2' | 'L3';
+  hash: string;  // For cache invalidation
+}
+
+class PromptCompiler {
+  private blocks: Map<string, PromptBlock> = new Map();
+
+  // Register reusable blocks
+  registerBlock(name: string, content: string, cacheLevel: CacheLevel): void {
+    this.blocks.set(name, {
+      name,
+      content,
+      tokens: estimateTokens(content),
+      cacheLevel,
+      hash: computeHash(content),
+    });
+  }
+
+  // Compile prompt from blocks
+  compile(blockNames: string[], dynamicContent: Record<string, string>): CompiledPrompt {
+    const usedBlocks: PromptBlock[] = [];
+    let content = '';
+
+    for (const name of blockNames) {
+      const block = this.blocks.get(name);
+      if (!block) {
+        throw new Error(`Unknown block: ${name}`);
+      }
+      usedBlocks.push(block);
+      content += block.content + '\n\n';
+    }
+
+    // Add dynamic content
+    for (const [key, value] of Object.entries(dynamicContent)) {
+      content += `## ${key}\n${value}\n\n`;
+    }
+
+    return {
+      content,
+      tokenEstimate: usedBlocks.reduce((sum, b) => sum + b.tokens, 0) + estimateTokens(Object.values(dynamicContent).join('')),
+      cacheKey: this.computeCacheKey(usedBlocks, dynamicContent),
+      locale: 'en',
+      cacheLevel: this.determineCacheLevel(usedBlocks),
+      blocks: usedBlocks,
+      version: this.computeVersion(usedBlocks),
+    };
+  }
+
+  private computeVersion(blocks: PromptBlock[]): string {
+    const hashes = blocks.map(b => b.hash).join('');
+    return computeHash(hashes).substring(0, 8);
+  }
+}
+
+// Usage
+const compiler = new PromptCompiler();
+
+// Register static blocks
+compiler.registerBlock('system-identity', SYSTEM_IDENTITY_PROMPT, 'L1');
+compiler.registerBlock('evaluation-criteria', EVALUATION_CRITERIA_PROMPT, 'L1');
+compiler.registerBlock('tool-definitions', TOOL_DEFINITIONS_PROMPT, 'L2');
+compiler.registerBlock('response-format', RESPONSE_FORMAT_PROMPT, 'L1');
+
+// Compile for request
+const prompt = compiler.compile(
+  ['system-identity', 'evaluation-criteria', 'tool-definitions', 'response-format'],
+  {
+    'Current Project': projectContext,
+    'Recent Memories': memoriesContext,
+    'User Message': userMessage,
+  }
+);
+
+console.log('Prompt version:', prompt.version);
+console.log('Estimated tokens:', prompt.tokenEstimate);
+```
+
+**Benefits:**
+
+- **Versioning**: Track prompt changes like code
+- **Testing**: Unit test individual blocks
+- **Caching**: Precise cache key computation
+- **Debugging**: Know exactly what's in each prompt
+- **Optimization**: Measure and reduce token usage

package/templates/rules/patterns-request-id-propagation.md

@@ -0,0 +1,137 @@
+---
+title: Request ID Propagation
+impact: MEDIUM
+impactDescription: Enables end-to-end request tracing across services
+tags: [patterns, observability, debugging]
+---
+
+## Request ID Propagation
+
+Propagate a unique request ID through all services for end-to-end tracing.
+
+**Implementation:**
+
+```typescript
+// src/lib/context.ts
+import { AsyncLocalStorage } from 'async_hooks';
+import { randomUUID } from 'crypto';
+
+interface RequestContext {
+  requestId: string;
+  userId?: string;
+  tenantId?: string;
+  startTime: number;
+}
+
+const asyncLocalStorage = new AsyncLocalStorage<RequestContext>();
+
+export function getRequestContext(): RequestContext | undefined {
+  return asyncLocalStorage.getStore();
+}
+
+export function getRequestId(): string {
+  return getRequestContext()?.requestId || 'no-request-id';
+}
+
+// Middleware
+export function requestContextMiddleware(req: Request, res: Response, next: NextFunction) {
+  const requestId = (req.headers['x-request-id'] as string) || randomUUID();
+
+  const context: RequestContext = {
+    requestId,
+    userId: req.user?.id,
+    tenantId: req.user?.tenantId,
+    startTime: Date.now(),
+  };
+
+  // Set response header
+  res.setHeader('x-request-id', requestId);
+
+  // Run handler within context
+  asyncLocalStorage.run(context, () => next());
+}
+```
+
+**Logger Integration:**
+
+```typescript
+// src/lib/logger.ts
+import { getRequestContext } from './context';
+
+class Logger {
+  private log(level: string, message: string, data: object = {}) {
+    const ctx = getRequestContext();
+
+    console.log(JSON.stringify({
+      level,
+      message,
+      timestamp: new Date().toISOString(),
+      requestId: ctx?.requestId,
+      userId: ctx?.userId,
+      tenantId: ctx?.tenantId,
+      ...data,
+    }));
+  }
+
+  info(message: string, data?: object) { this.log('info', message, data); }
+  error(message: string, data?: object) { this.log('error', message, data); }
+  // ...
+}
+
+export const logger = new Logger();
+```
+
+**Propagate to External Services:**
+
+```typescript
+// Include requestId in external API calls
+async function callExternalService(endpoint: string, data: object) {
+  const requestId = getRequestId();
+
+  return fetch(endpoint, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-Request-Id': requestId,  // Propagate to external service
+    },
+    body: JSON.stringify(data),
+  });
+}
+
+// Include in LLM metadata
+async function callLLM(request: LLMRequest) {
+  const requestId = getRequestId();
+
+  return model.complete({
+    ...request,
+    metadata: {
+      user_id: getRequestContext()?.userId,
+      request_id: requestId,  // Appears in the provider dashboard
+    },
+  });
+}
+```
+
+**Database Query Tagging:**
+
+```typescript
+// Tag queries with request ID for debugging
+async function query<T>(sql: string, params: unknown[]): Promise<T[]> {
+  const requestId = getRequestId();
+
+  // Add comment with request ID (visible in slow query logs)
+  const taggedSql = `/* requestId=${requestId} */ ${sql}`;
+
+  return db.query(taggedSql, params);
+}
+```
+
+**Full Request Trace Example:**
+
+```
+[2025-01-24T10:30:00.000Z] {"level":"info","message":"Request started","requestId":"abc-123","path":"/api/chat"}
+[2025-01-24T10:30:00.050Z] {"level":"info","message":"Memory retrieval","requestId":"abc-123","memories":5}
+[2025-01-24T10:30:00.100Z] {"level":"info","message":"LLM request started","requestId":"abc-123","model":"balanced"}
+[2025-01-24T10:30:02.500Z] {"level":"info","message":"LLM request completed","requestId":"abc-123","tokens":1234}
+[2025-01-24T10:30:02.550Z] {"level":"info","message":"Request completed","requestId":"abc-123","duration":2550}
+```

package/templates/rules/process-adr-and-journal.md

@@ -0,0 +1,50 @@
+---
+title: ADR Discipline and Working Journal
+impact: HIGH
+impactDescription: Makes structural decisions traceable and reversible-by-record, so the system can be picked up by anyone without re-litigating settled choices
+tags: [process, adr, journal, traceability, governance]
+---
+
+## ADR Discipline and Working Journal
+
+A structural decision that lives only in someone's head is a decision that will be re-debated. Two lightweight records keep the system legible: ADRs for structural choices, a journal for the running thread.
+
+**ADR (Architecture Decision Record):**
+
+- One ADR per structural decision: a boundary, a port, a model, a persistence choice, a safety guard.
+- An accepted ADR is **never edited**. A new decision that changes it is a **new ADR that supersedes or refines** the old one (the trail stays intact).
+- Each ADR records its **trigger**: the objective signal that would reopen it. "Default: sober; trigger: this measured condition." A decision with no trigger is a decision you cannot revisit on evidence.
+
+```
+# ADR-008 - Grounding guard over an expanded set
+Status: accepted · Refines: ADR-001 · Date: 2026-06-22
+Context: the guard rejected a legitimate figure present in a served fact's label.
+Decision: the grounded set = fact values ∪ numbers in served labels ∪ years.
+Trigger to revisit: wiring the model in structured outputs -> switch to {fN}
+                    slot references -> write ADR-009 at that point.
+Consequences: the unit test now feeds realistic facts with their labels.
+```
+
+**Journal (one entry per working session):**
+
+```
+## YYYY-MM-DD - short title
+- Done: ...
+- Decided: ... (if structural, point to ADR-xxx)
+- Blocked / to dig: ...
+- Next: ...
+```
+
+The journal carries minor decisions and progress; structural ones graduate to an ADR. Together they answer "why is it like this?" without archaeology.
+
+**Commits and the code as evidence:**
+
+- Conventional commits (`feat:`, `fix:`, `refactor:`, `docs:`) so history is scannable.
+- The code is the final proof: a decision that matters has a test, a guard, or a runnable check that demonstrates it. An ADR points at that proof, it does not replace it.
+
+**Checklist:**
+
+- [ ] Every structural choice has an ADR with an explicit revisit trigger.
+- [ ] Accepted ADRs are immutable; change means a new, superseding ADR.
+- [ ] A journal entry closes each session (done / decided / blocked / next).
+- [ ] Decisions that matter are backed by a test or guard in the code.

package/templates/rules/provider-llm-auto-detection.md

@@ -0,0 +1,54 @@
+---
+title: Model Provider as an Adapter (Detected, Never Hardcoded)
+impact: CRITICAL
+impactDescription: Keeps the model behind a port so the provider can change by configuration without touching the core
+tags: [provider, llm, embeddings, ports, configuration, portability]
+---
+
+## Model Provider as an Adapter
+
+> **The model is rented; the architecture is owned. So the model sits behind a port, like any other external service.**
+
+The core depends on a `ModelPort` (and, if used, an `EmbeddingPort`), never on a vendor SDK. Which provider answers is a configuration concern resolved at the boundary, by detecting available credentials. The same core runs against any provider, a gateway, a local model, or a mock, with no code change.
+
+**Incorrect:**
+
+```typescript
+// Vendor hardcoded into reachable code; swapping providers is a rewrite.
+import VendorSDK from "@some-vendor/llm-sdk";
+const client = new VendorSDK({ apiKey: process.env.VENDOR_API_KEY! }); // BAD: a vendor wired into the core
+```
+
+**Correct:**
+
+```typescript
+// 1. The core knows a port, nothing else.
+interface ModelPort {
+  complete(req: CompletionRequest): Promise<CompletionResult>;
+}
+
+// 2. The provider is resolved at the boundary from available config.
+type ModelConfig = { provider: string; gatewayUrl?: string; model: string };
+
+function resolveModelProvider(): ModelConfig {
+  // Prefer a gateway (one egress, one place to attach the real key), then direct.
+  if (env.MODEL_GATEWAY_URL) return { provider: "gateway", gatewayUrl: env.MODEL_GATEWAY_URL, model: env.MODEL };
+  if (env.MODEL_PROVIDER)    return { provider: env.MODEL_PROVIDER, model: env.MODEL };
+  throw new ConfigError("No model provider configured (set MODEL_GATEWAY_URL or MODEL_PROVIDER).");
+}
+
+// 3. One adapter per provider implements the port. The core never sees the difference.
+class GatewayModelAdapter implements ModelPort { /* ... */ }
+class MockModelAdapter implements ModelPort { /* deterministic, for tests and the floor */ }
+```
+
+**Why a gateway is the sober default:** a single egress point is where the real credential is attached by infrastructure (see *Secrets at the Network Boundary*), where residency and fallback live, and where you swap providers without redeploying the core.
+
+**Embeddings are a separate port.** The embedding provider is detected the same way and is independent of the model provider; do not assume one implies the other.
+
+**Checklist:**
+
+- [ ] No vendor SDK imported from the core; only the adapter imports it.
+- [ ] Provider resolved at the boundary from config, with a clear error if nothing is set.
+- [ ] A deterministic mock adapter exists for tests and the offline floor.
+- [ ] Embeddings have their own port, resolved independently.

package/templates/rules/provider-no-crash-missing-env.md

@@ -0,0 +1,67 @@
+---
+title: Graceful Degradation of Optional Services
+impact: HIGH
+impactDescription: Lets the app start and run wherever it is deployed, enabling features by available config rather than crashing on a missing variable
+tags: [provider, configuration, resilience, deployment]
+---
+
+## Graceful Degradation of Optional Services
+
+> **Required missing: fail fast and loud. Optional missing: disable the feature, keep running.**
+
+The application must start regardless of which optional services are configured. Only truly required dependencies (a database of record, at least one model provider) may stop startup. Everything optional degrades to a sober default.
+
+**Required vs optional:**
+
+| Category | Required (may stop startup) | Optional (must degrade) |
+|---|---|---|
+| Database of record | `DATABASE_URL` | - |
+| Model | at least one provider | a specific provider |
+| Search / enrichment | none | its API key |
+| Vector / memory store | none | its URL |
+| Telemetry sink | none | its token |
+
+**Incorrect:**
+
+```typescript
+// Throws at module load for an optional service.
+const search = new SearchClient(env.SEARCH_API_KEY!);   // BAD: crashes if absent
+```
+
+**Correct:**
+
+```typescript
+// Lazy, returns null when unavailable; callers fall back.
+let search: SearchClient | null = null;
+export function getSearch(): SearchClient | null {
+  if (search) return search;
+  if (!env.SEARCH_API_KEY) { log.info("[SEARCH] not configured - disabled"); return null; }
+  return (search = new SearchClient(env.SEARCH_API_KEY));
+}
+
+export async function enrich(q: string): Promise<Result[]> {
+  const s = getSearch();
+  return s ? s.search(q) : [];          // sober default, not a crash
+}
+```
+
+**Log the resolved configuration at startup** so the active shape is visible (never log secrets):
+
+```typescript
+log.info("[STARTUP] services", {
+  database: !!env.DATABASE_URL,
+  model: modelConfig.provider,
+  search: !!getSearch(),
+  memory: !!getMemory(),
+});
+```
+
+This is the "sober default plus trigger" posture applied to configuration: ship with the minimum that runs everywhere, light up a capability only when its dependency is actually present.
+
+**This is bimodal deployment.** The same binary runs in a *minimal* mode (only required dependencies present) and a *full* mode (every optional dependency present), with the mode resolved by feature detection at startup, not by a separate build. The interface signals what is active rather than failing silently. Minimal mode is what makes the system deployable in a restricted or air-gapped environment without a code change.
+
+**Checklist:**
+
+- [ ] App starts with only the required variables set.
+- [ ] Each optional service degrades to a defined fallback, never a crash.
+- [ ] Resolved configuration (not secrets) is logged once at startup.

package/templates/rules/quality-codebase-metrics.md

@@ -0,0 +1,115 @@
+---
+title: Codebase Metrics Thresholds
+impact: MEDIUM
+impactDescription: Identifies code quality issues before they become problems
+tags: [quality, metrics, maintainability]
+---
+
+## Codebase Metrics Thresholds
+
+Monitor codebase health with these thresholds.
+
+**File Size Thresholds:**
+
+| Metric | Warning | Refactor Needed |
+|--------|---------|-----------------|
+| File > 300 lines | ⚠️ | > 500 lines |
+| Function > 50 lines | ⚠️ | > 100 lines |
+| Cyclomatic complexity > 10 | ⚠️ | > 15 |
+| Nesting depth > 4 | ⚠️ | > 6 |
+
+**Code Smell Indicators:**
+
+| Pattern | Threshold | Action |
+|---------|-----------|--------|
+| Switch statement cases | > 10 | Use registry pattern |
+| Function parameters | > 5 | Use options object |
+| Class methods | > 15 | Split class |
+| Import statements | > 20 | Check for god file |
+| Tools count | > 30 | Group by domain |
+| In-memory Maps | Any | Document for scaling |
+
+**Automated Checks:**
+
+```typescript
+// scripts/codebase-metrics.ts
+import * as fs from 'fs';
+import * as path from 'path';
+
+interface FileMetrics {
+  path: string;
+  lines: number;
+  functions: number;
+  maxFunctionLength: number;
+  imports: number;
+  switchCases: number;
+}
+
+function analyzeFile(filePath: string): FileMetrics {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const lines = content.split('\n');
+
+  return {
+    path: filePath,
+    lines: lines.length,
+    functions: (content.match(/function\s+\w+|=>\s*{|\w+\s*\([^)]*\)\s*{/g) || []).length,
+    maxFunctionLength: calculateMaxFunctionLength(content),
+    imports: (content.match(/^import\s+/gm) || []).length,
+    switchCases: (content.match(/case\s+/g) || []).length,
+  };
+}
+
+function reportIssues(metrics: FileMetrics[]): void {
+  const issues: string[] = [];
+
+  for (const file of metrics) {
+    if (file.lines > 500) {
+      issues.push(`${file.path}: ${file.lines} lines (max 500)`);
+    } else if (file.lines > 300) {
+      issues.push(`${file.path}: ${file.lines} lines (warning > 300)`);
+    }
+
+    if (file.switchCases > 20) {
+      issues.push(`${file.path}: ${file.switchCases} switch cases - use registry pattern`);
+    }
+
+    if (file.imports > 20) {
+      issues.push(`${file.path}: ${file.imports} imports - possible god file`);
+    }
+  }
+
+  if (issues.length > 0) {
+    console.log('Codebase Issues Found:');
+    issues.forEach(i => console.log(i));
+    process.exit(1);  // Fail CI
+  } else {
+    console.log('yes No codebase issues found');
+  }
+}
+```
+
+**ESLint Rules:**
+
+```javascript
+// .eslintrc.js
+module.exports = {
+  rules: {
+    'max-lines': ['warn', { max: 300, skipBlankLines: true, skipComments: true }],
+    'max-lines-per-function': ['warn', { max: 50, skipBlankLines: true, skipComments: true }],
+    'max-depth': ['warn', 4],
+    'max-params': ['warn', 5],
+    'complexity': ['warn', 10],
+  },
+};
+```
+
+**PR Checklist:**
+
+```markdown
+## Code Quality Checklist
+- [ ] No file exceeds 500 lines
+- [ ] No function exceeds 100 lines
+- [ ] No switch with > 10 cases
+- [ ] New Maps documented for scaling
+- [ ] Complex logic has comments
+```