runward 0.6.0

package/templates/rules/async-post-turn-pipeline.md

@@ -0,0 +1,96 @@
+---
+title: Post-Turn Pipeline (Keep the Interactive Turn Thin)
+impact: HIGH
+impactDescription: Keeps response latency bound to what the answer needs by moving extraction, consolidation and summarization into an isolated, event-driven pipeline that runs after the turn
+tags: [async, pipeline, events, latency, memory, provenance]
+---
+
+## Post-Turn Pipeline
+
+> **The interactive turn does what the answer needs. Everything else leaves the turn.**
+
+A turn that extracts facts, consolidates memory and writes episode summaries before replying makes the user pay for work the response never needed. The turn stays thin: retrieve context, decide, answer, persist the interaction event. Everything that serves the *next* turn rather than this one — fact extraction, memory consolidation, episode summarization, pre-warming the likely next context — moves to a post-turn pipeline, triggered by an event emitted when the turn completes.
+
+Three properties are non-negotiable:
+
+1. **The provenance fingerprint is deposited at emission.** The event carries a fingerprint of what the model actually saw. By the time a pipeline step runs — possibly minutes later, possibly on retry — working state may have changed; the step works from the recorded truth, not from whatever memory looks like now.
+2. **Each step is isolated with its own bounded retry.** A flaky summarizer retries on its own schedule without touching its siblings.
+3. **One step failing never fails the others.** No shared fate: fact extraction completes even when summarization is down.
+
+**Incorrect:**
+
+```typescript
+// Everything inline: the user waits for work the answer does not need.
+async function handleTurn(input: UserInput): Promise<Reply> {
+  const context = await memory.retrieve(input);
+  const reply = await orchestrator.answer(input, context);
+
+  await extractFacts(reply);          // BAD: not needed to answer
+  await consolidateMemory();          // BAD: batch work on the hot path
+  await summarizeEpisode(reply);      // BAD: if this throws, the turn fails
+  await prewarmNextContext(input);    // BAD: p95 now includes four jobs
+
+  return reply;
+}
+```
+
+**Correct:**
+
+```typescript
+// Thin turn: answer, persist, emit. The pipeline runs after the reply is out.
+async function handleTurn(input: UserInput): Promise<Reply> {
+  const context = await memory.retrieve(input);
+  const reply = await orchestrator.answer(input, context);
+
+  await events.emit({
+    type: 'turn.completed',
+    turnId: reply.turnId,
+    provenance: fingerprint(context),  // what the model saw, sealed now
+    occurredAt: new Date(),
+  });
+  return reply;  // latency = retrieve + answer + one event write
+}
+
+// Each step: its own handler, its own bounded retry, no shared fate.
+const steps: PipelineStep[] = [
+  { name: 'extract-facts',   run: extractFacts },
+  { name: 'consolidate',     run: consolidateMemory },
+  { name: 'summarize',       run: summarizeEpisode },
+  { name: 'prewarm-context', run: prewarmNextContext },
+];
+
+events.on('turn.completed', async (event) => {
+  const results = await Promise.allSettled(
+    steps.map(step =>
+      withRetry(() => step.run(event), { maxRetries: 3, name: step.name })
+    )
+  );
+  results.forEach((r, i) => {
+    if (r.status === 'rejected') {
+      log.error('pipeline.step.failed', {
+        step: steps[i].name,
+        turnId: event.turnId,
+        error: String(r.reason),
+      });
+      // Siblings have already succeeded or failed on their own.
+    }
+  });
+});
+```
+
+**Why this matters:**
+
+- **Latency**: the user waits for the answer, not for the housekeeping. Four background jobs on the hot path can double p95 for zero visible value.
+- **Resilience**: a degraded summarizer no longer takes fact extraction — or the turn itself — down with it. Each step degrades alone.
+- **Audit**: because the fingerprint is sealed at emission, a step that runs late or on retry still reads exactly what the turn saw. Provenance survives asynchrony.
+- **Cost**: pipeline steps are off the hot path, so they can run on cheaper model tiers and absorb backpressure without touching the user experience.
+
+Post-turn steps are background jobs like any other: they carry the four guardrails — bounded retry, idempotency, bounded concurrency, job observability (see *Background Job Guardrails*).
+
+**Checklist:**
+
+- [ ] The interactive turn performs only what the response requires; everything else is triggered by a turn-completed event.
+- [ ] The event carries the provenance fingerprint, deposited at emission — steps never read mutable state to learn what the model saw.
+- [ ] Each pipeline step has its own bounded retry, independent of its siblings.
+- [ ] A step's failure is logged with the turn id and isolated; the other steps complete.
+- [ ] Pipeline steps follow the background-job guardrails (idempotency keys, concurrency caps, queue metrics).

package/templates/rules/async-scheduled-maintenance.md

@@ -0,0 +1,95 @@
+---
+title: Scheduled Maintenance (The Cron Updates and Cools, It Never Destroys Truth)
+impact: MEDIUM
+impactDescription: Keeps memory, derived views and the journal healthy over months of operation through periodic decay, pruning and cold archiving that never touch the source of truth
+tags: [async, cron, maintenance, memory, retention, archive]
+---
+
+## Scheduled Maintenance
+
+> **The cron updates and cools. It never destroys the truth.**
+
+Some upkeep has no triggering event — its trigger is the passage of time. Memory scores decay as facts age; derived links drift past their retention; the journal accumulates segments nobody reads hot anymore; trends only appear across weeks of aggregates; reminders come due; legally imposed erasure deadlines arrive. This work belongs to scheduled maintenance jobs, not to the interactive turn and not to the post-turn pipeline.
+
+One dividing line governs everything the cron touches:
+
+- **Derived data** — scores, derived links, indexes, caches, summaries — may be decayed, pruned or rebuilt freely: it is recomputable from the journal.
+- **The immutable journal** — the source of truth — is never deleted by maintenance. Old segments are moved to cold storage, checksum verified, and remain retrievable for audit and replay.
+- **Enforced erasure** — right-to-be-forgotten, legal retention limits — is the only true deletion, and it is an explicit, audited command with its own path. It is never a side effect of a cleanup batch.
+
+**Incorrect:**
+
+```typescript
+// A "cleanup" cron that quietly destroys the source of truth.
+cron.schedule('0 3 * * *', async () => {
+  // BAD: the journal is the truth — audit and replay just died
+  await db.query(`DELETE FROM journal WHERE created_at < now() - interval '90 days'`);
+  // BAD: silent disappearance — nothing records why the fact vanished
+  await db.query(`DELETE FROM memories WHERE score < 0.2`);
+});
+```
+
+**Correct:**
+
+```typescript
+// Each job declares what it touches; none of them deletes truth.
+const maintenance: MaintenanceJob[] = [
+  {
+    name: 'decay-scores', schedule: '@daily',
+    run: () => memoryStore.applyDecay({ halfLifeDays: 30 }),
+    // Adjusts ranking; low scores demote, they do not delete.
+  },
+  {
+    name: 'prune-derived-links', schedule: '@daily',
+    run: () => linkStore.pruneDerived({ olderThan: RETENTION }),
+    // Derived only: every pruned link is recomputable from the journal.
+  },
+  {
+    name: 'archive-journal-segments', schedule: '@weekly',
+    run: async () => {
+      const segments = await journal.segmentsOlderThan(HOT_WINDOW);
+      for (const s of segments) {
+        const archived = await coldStorage.put(s);
+        if (archived.checksum !== s.checksum) throw new Error('archive mismatch');
+        await journal.releaseHotCopy(s.id, { archivedAt: archived.location });
+      }
+      // Moved and verified — never deleted. Audit can still unfold it.
+    },
+  },
+  {
+    name: 'detect-trends', schedule: '@weekly',
+    run: () => trends.computeOverAggregates({ window: '90d' }),
+  },
+  {
+    name: 'due-reminders', schedule: '@hourly',
+    run: () => reminders.emitDue(),
+  },
+  {
+    name: 'enforced-erasure', schedule: '@daily',
+    run: async () => {
+      // The only true deletion: explicit requests, own path, audited.
+      for (const req of await erasureRequests.pending()) {
+        await eraseAcrossStores(req.subjectId, req.scope);
+        await auditLog.append({ type: 'erasure.executed', request: req.id });
+      }
+    },
+  },
+];
+```
+
+**Why this matters:**
+
+- **Retrieval quality**: without decay and pruning, ranking drowns in stale facts; the cron is what keeps recall honest as the system ages.
+- **Bounded cost without lost history**: cold archiving caps hot-storage growth while audit and replay keep working — the truth cools, it does not vanish.
+- **Compliance both ways**: enforced erasure is provable (explicit request, audit record), and nothing *else* can silently delete regulated data, because no other job is allowed to.
+- **Recovery**: after a bad consolidation or a corrupted index, every derived structure can be rebuilt — precisely because maintenance never touched the journal.
+
+Maintenance jobs are background jobs like any other: bounded retry, idempotency, bounded concurrency, queue metrics (see *Background Job Guardrails*). A weekly job that fails silently for a month is a slow outage.
+
+**Checklist:**
+
+- [ ] Every maintenance job is classified: derived (may decay/prune/rebuild), journal (archive only, verify then release), or erasure (explicit and audited).
+- [ ] No scheduled job issues deletes against the journal; archiving verifies checksums before releasing hot copies.
+- [ ] Score decay demotes and invalidation supersedes — nothing silently disappears from memory.
+- [ ] Enforced erasure runs on explicit requests through its own path, and writes an audit record per execution.
+- [ ] Maintenance jobs follow the background-job guardrails and alert when a scheduled run is missed or failing.

package/templates/rules/cache-three-tier-architecture.md

@@ -0,0 +1,44 @@
+---
+title: Prompt Cache Stability (a Cost Lever, Provider-Specific)
+impact: MEDIUM
+impactDescription: Cuts input-token cost when a provider bills cached prefixes cheaper, by keeping the stable part of the prompt byte-identical across requests
+tags: [cache, llm, cost, observability]
+---
+
+## Prompt Cache Stability
+
+This is a **cost lever, not an architecture principle.** Cost is driven first by the model boundary (keep deterministic work out of the model) and by routing; prompt caching is a secondary optimisation, and only where the provider bills a cached prefix cheaper than a fresh one. Reach for it once cost is measured and the prompt has a genuinely stable prefix, not before.
+
+> **Cache stability beats token reduction.** A layer that varies between requests gets a 0% cache hit and costs more than the same layer sent stable. A 15K-token stable prefix at 90% hit is cheaper than a 10K-token prefix at 0%.
+
+**Order the prompt from most stable to most dynamic, and mark the stable cut points:**
+
+```
+Layer 1 - CORE      identity, methodology, format, safety rules   changes: never (mid-session)
+Layer 2 - TOOLS     generic tool schemas and guidelines           changes: on feature updates
+Layer 3 - DYNAMIC   retrieved context, history, the user message  changes: every request
+```
+
+**Correct:**
+
+```typescript
+const response = await model.complete({
+  system: [
+    { text: corePrompt,  cacheable: true },   // stable prefix, cached
+    { text: toolsPrompt, cacheable: true },   // semi-stable, cached
+    { text: dynamicContext },                 // never cached
+  ],
+  messages,
+});
+```
+
+**What breaks a cache (anti-patterns):** injecting user/tenant data into Layer 1-2, timestamps in stable layers, conditionally including sections, reordering content within a cached layer. Keep variable content in Layer 3, always.
+
+**Measure it or skip it:** track cache-read vs cache-write tokens in your LLM metrics. If the hit rate on the stable prefix is not materially above zero, the prefix is not actually stable and the lever is doing nothing.
+
+**Checklist:**
+
+- [ ] Cost is measured first; caching is applied as a deliberate lever, not by default.
+- [ ] The stable prefix is byte-identical across requests (no per-request variation).
+- [ ] Variable content lives only in the dynamic layer.
+- [ ] Cache hit rate on the stable prefix is monitored, not assumed.

package/templates/rules/checklist-day-zero-project.md

@@ -0,0 +1,97 @@
+---
+title: Day-Zero Project Setup Checklist
+impact: CRITICAL
+impactDescription: Starts a project on the foundation that prevents costly refactors, with the core engineering disciplines wired from the first commit
+tags: [checklist, architecture, setup, project]
+---
+
+## Day-Zero Project Setup Checklist
+
+The foundation to lay before the first feature. Sober by default: only what runs everywhere, with the disciplines that are expensive to retrofit wired from commit one.
+
+```
+ARCHITECTURE (30 min)
+├── [ ] Hexagonal structure (core/, adapters/, infrastructure/)
+├── [ ] Ports defined (even if empty); the model is one of them
+├── [ ] Config typed and validated once with Zod (no scattered process.env)
+├── [ ] Unified error model
+└── [ ] Structured JSON logger with request-id propagation
+
+BOUNDARIES (15 min)  [the core disciplines]
+├── [ ] Model behind a port, resolved at the boundary (no vendor SDK in core)
+├── [ ] Deterministic boundary planned: facts from a store, model writes prose
+├── [ ] Optional services degrade gracefully (absent != crash); logged at startup
+└── [ ] Secrets read only in typed config; never in code, never in the model
+
+QUALITY (15 min)
+├── [ ] Lint + format configured
+├── [ ] Pre-commit hooks
+├── [ ] Domain test template (the floor's success criterion as a test)
+├── [ ] ADR template + first ADRs for structural choices (with revisit triggers)
+├── [ ] JOURNAL.md for per-session entries
+└── [ ] Minimal README
+
+INFRA (15 min)
+├── [ ] .env.example with the required vars only, optional ones commented
+├── [ ] Forward-only migration runner (numbered, contiguous, branch-first)
+├── [ ] CI pipeline (lint + test + schema-drift)
+├── [ ] Healthcheck + readiness endpoint
+└── [ ] Conventional commits
+```
+
+**Minimum directory structure:**
+
+This is the layout of the reference scaffold; follow it so every project speaks the same structure.
+
+```
+src/
+├── core/                      # Pure: no framework, no vendor SDK reaches here
+│   ├── domain/                # entities, value objects, zod types, guards
+│   ├── application/           # use-cases (orchestration)
+│   └── ports/
+│       ├── in/                # primary ports (how the app is driven)
+│       └── out/               # secondary ports (model, store, clock, tools)
+├── adapters/
+│   ├── primary/               # http, cli
+│   └── secondary/             # model, persistence, tools
+├── infrastructure/
+│   ├── config/                # zod-typed, validated once; the only reader of env
+│   ├── container.ts           # wires adapters to ports (DI)
+│   ├── middleware.ts          # the single cross-cutting surface (logs, request-id, cost)
+│   ├── registry.ts            # tool registry (an index, not a bus)
+│   └── observability/
+├── eval/                      # behavioural eval harness
+db/ (when persisted)
+└── migrations/                # 0001_init.sql, forward-only
+test/                          # domain · contract (schema-drift) · integration · cost-cap
+CLAUDE.md · JOURNAL.md · README.md · docs/adr/
+```
+
+**Minimum `.env.example` (required only; optional commented):**
+
+```bash
+# Required
+DATABASE_URL=postgresql://user:pass@host/db?sslmode=verify-full&channel_binding=require
+MODEL_GATEWAY_URL=        # or MODEL_PROVIDER + MODEL
+MODEL=
+
+# Optional (feature lights up only if present)
+# SEARCH_API_KEY=
+# MEMORY_URL=
+# TELEMETRY_TOKEN=
+LOG_LEVEL=info
+```
+
+**Startup log (resolved config, never secrets):**
+
+```typescript
+log.info("[STARTUP] config", {
+  env: config.env,
+  model: config.model.provider,
+  database: !!config.database.url,
+  search: config.optional.search,
+  memory: config.optional.memory,
+});
+```
+
+The split is deliberate: the *Boundaries* block is what separates an agentic system that holds up from one that does not. It is cheap on day zero and expensive on day ninety.

package/templates/rules/checklist-pre-production-observability.md

@@ -0,0 +1,99 @@
+---
+title: Pre-Production Observability Checklist
+impact: HIGH
+impactDescription: Ensures you can monitor and debug production issues
+tags: [checklist, observability, production, deployment]
+---
+
+## Pre-Production Observability Checklist
+
+Observability items to validate before production deployment.
+
+```
+OBSERVABILITY CHECKLIST
+├── [ ] Structured logs (JSON format)
+├── [ ] Request ID propagated through all services
+├── [ ] LLM metrics tracked (tokens, cost, latency, model)
+├── [ ] Error rates tracked and alerted
+├── [ ] Alerts configured for critical metrics
+├── [ ] Dashboard for operational monitoring
+├── [ ] Log retention policy defined
+└── [ ] Sensitive data redacted from logs
+```
+
+**Structured Logging:**
+
+```typescript
+// BAD: Incorrect: unstructured logs
+console.log(`User ${userId} created project ${projectId}`);
+
+// GOOD: Correct: structured JSON
+logger.info('Project created', {
+  userId,
+  projectId,
+  tenantId,
+  requestId: ctx.requestId,
+  duration: Date.now() - start,
+});
+```
+
+**Request ID Propagation:**
+
+```typescript
+// Middleware to create/propagate request ID
+function requestIdMiddleware(req: Request, res: Response, next: NextFunction) {
+  const requestId = req.headers['x-request-id'] as string || crypto.randomUUID();
+  req.requestId = requestId;
+  res.setHeader('x-request-id', requestId);
+
+  // Add to async local storage for logging
+  asyncLocalStorage.run({ requestId }, next);
+}
+
+// All logs include requestId
+const logger = {
+  info(message: string, data: object) {
+    const ctx = asyncLocalStorage.getStore();
+    console.log(JSON.stringify({
+      level: 'info',
+      message,
+      requestId: ctx?.requestId,
+      timestamp: new Date().toISOString(),
+      ...data,
+    }));
+  },
+};
+```
+
+**LLM Metrics:**
+
+```typescript
+// Track every LLM call
+interface LLMMetrics {
+  model: string;
+  inputTokens: number;
+  outputTokens: number;
+  latencyMs: number;
+  cached: boolean;
+  estimatedCost: number;
+}
+
+function logLLMMetrics(metrics: LLMMetrics) {
+  logger.info('LLM request completed', metrics);
+
+  // Send to metrics service
+  telemetry.record('llm_request', {
+    ...metrics,
+    timestamp: Date.now(),
+  });
+}
+```
+
+**Alert Configuration:**
+
+| Metric | Threshold | Action |
+|--------|-----------|--------|
+| Error rate | > 5% over 5 min | Page on-call |
+| LLM latency P95 | > 5s | Investigate |
+| Cache hit rate | < 50% | Investigate |
+| Cost per request | > $0.10 | Review routing |

package/templates/rules/checklist-pre-production-performance.md

@@ -0,0 +1,109 @@
+---
+title: Pre-Production Performance Checklist
+impact: HIGH
+impactDescription: Ensures application performs well under production load
+tags: [checklist, performance, production, deployment]
+---
+
+## Pre-Production Performance Checklist
+
+Performance items to validate before production deployment.
+
+```
+PERFORMANCE CHECKLIST
+├── [ ] LLM cache 3-tier implemented
+├── [ ] Smart routing active (Fast/Balanced/Deep)
+├── [ ] DB connection pooling configured
+├── [ ] DB queries indexed (check slow query log)
+├── [ ] Frontend assets optimized (images, bundle) if a UI is served
+├── [ ] Code splitting enabled
+├── [ ] Bundle size analyzed (<500KB initial)
+├── [ ] API response times measured (<200ms P95 for non-LLM)
+└── [ ] Load testing completed
+```
+
+**Cache Verification:**
+
+```typescript
+// Log cache hit rates at startup and periodically
+setInterval(() => {
+  const stats = cacheStats.get();
+  logger.info('Cache statistics', {
+    layer1HitRate: stats.layer1.hits / stats.layer1.total,
+    layer2HitRate: stats.layer2.hits / stats.layer2.total,
+    totalSavings: stats.estimatedSavings,
+  });
+}, 60000);
+
+// Alert if cache performance degrades
+if (stats.layer1HitRate < 0.8) {
+  logger.warn('Layer 1 cache hit rate below threshold', { rate: stats.layer1HitRate });
+}
+```
+
+**Database Performance:**
+
+```typescript
+// Enable slow query logging
+const pool = new Pool({
+  connectionString: process.env.DATABASE_URL,
+  max: 20,
+});
+
+// Log slow queries
+pool.on('query', (event) => {
+  if (event.duration > 100) {  // > 100ms
+    logger.warn('Slow query detected', {
+      query: event.query.substring(0, 200),
+      duration: event.duration,
+    });
+  }
+});
+```
+
+**Bundle Analysis:**
+
+```bash
+# Analyze bundle size
+npm run build -- --analyze
+
+# Check for large dependencies
+npx @next/bundle-analyzer
+```
+
+**Load Testing:**
+
+```typescript
+// k6 load test script
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+
+export const options = {
+  stages: [
+    { duration: '2m', target: 50 },   // Ramp up
+    { duration: '5m', target: 50 },   // Sustain
+    { duration: '2m', target: 100 },  // Spike
+    { duration: '2m', target: 0 },    // Ramp down
+  ],
+  thresholds: {
+    http_req_duration: ['p(95)<500'],  // 95% of requests < 500ms
+    http_req_failed: ['rate<0.01'],    // Error rate < 1%
+  },
+};
+
+export default function () {
+  const res = http.get('https://api.example.com/health');
+  check(res, { 'status is 200': (r) => r.status === 200 });
+  sleep(1);
+}
+```
+
+**Performance Targets:**
+
+| Metric | Target | Critical |
+|--------|--------|----------|
+| API response (non-LLM) | <200ms P95 | >500ms |
+| LLM response (Fast) | <500ms P95 | >2s |
+| LLM response (Balanced) | <2s P95 | >5s |
+| Initial bundle size | <500KB | >1MB |
+| Cache hit rate (L1) | >80% | <60% |

package/templates/rules/checklist-pre-production-resilience.md

@@ -0,0 +1,99 @@
+---
+title: Pre-Production Resilience Checklist
+impact: CRITICAL
+impactDescription: Ensures application handles failures gracefully in production
+tags: [checklist, resilience, production, deployment]
+---
+
+## Pre-Production Resilience Checklist
+
+Resilience items that MUST be validated before any production deployment.
+
+```
+RESILIENCE CHECKLIST
+├── [ ] LLM retry with exponential backoff
+├── [ ] Timeout on ALL external requests (LLM, APIs, DB)
+├── [ ] Healthcheck endpoint (/health or /api/health)
+├── [ ] Readiness probe (for Kubernetes)
+├── [ ] Graceful shutdown (handle SIGTERM)
+├── [ ] Fallback providers configured (a model gateway or manual)
+├── [ ] Circuit breaker for flaky services
+├── [ ] Fail-open for non-critical services
+└── [ ] Error boundaries in UI (React)
+```
+
+**Incorrect:**
+
+```typescript
+// No timeout, no retry
+const response = await fetch(externalApi);  // BAD: Can hang forever
+
+// No graceful shutdown
+process.on('SIGTERM', () => process.exit(0));  // BAD: Drops in-flight requests
+```
+
+**Correct:**
+
+```typescript
+// Timeout on external calls
+const controller = new AbortController();
+const timeout = setTimeout(() => controller.abort(), 30000);
+
+try {
+  const response = await fetch(externalApi, { signal: controller.signal });
+} finally {
+  clearTimeout(timeout);
+}
+
+// Graceful shutdown
+let isShuttingDown = false;
+
+process.on('SIGTERM', async () => {
+  console.info('[SHUTDOWN] Received SIGTERM, starting graceful shutdown');
+  isShuttingDown = true;
+
+  // Stop accepting new requests
+  server.close();
+
+  // Wait for in-flight requests (max 30s)
+  await Promise.race([
+    waitForInflightRequests(),
+    sleep(30000),
+  ]);
+
+  // Close database connections
+  await db.destroy();
+
+  console.info('[SHUTDOWN] Graceful shutdown complete');
+  process.exit(0);
+});
+
+// Healthcheck endpoint
+app.get('/health', (req, res) => {
+  if (isShuttingDown) {
+    return res.status(503).json({ status: 'shutting_down' });
+  }
+  res.json({ status: 'healthy', timestamp: new Date().toISOString() });
+});
+
+// Readiness probe (checks dependencies)
+app.get('/ready', async (req, res) => {
+  try {
+    await db.query('SELECT 1');
+    res.json({ status: 'ready' });
+  } catch (error) {
+    res.status(503).json({ status: 'not_ready', error: error.message });
+  }
+});
+```
+
+**LLM Retry Configuration:**
+
+```typescript
+const LLM_RETRY_CONFIG = {
+  maxRetries: 3,
+  initialDelayMs: 1000,
+  maxDelayMs: 10000,
+  retryableErrors: ['rate_limit_error', 'overloaded_error', 'api_error'],
+};
+```