runward 0.6.0

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

@@ -0,0 +1,86 @@
+---
+title: Pre-Production Security Checklist
+impact: CRITICAL
+impactDescription: Ensures security requirements are met before production deployment
+tags: [checklist, security, production, deployment]
+---
+
+## Pre-Production Security Checklist
+
+Security items that MUST be validated before any production deployment.
+
+```
+SECURITY CHECKLIST
+├── [ ] Secrets in env vars only (not in code, not in logs)
+├── [ ] Input validation with Zod on ALL external inputs
+├── [ ] Rate limiting configured and tested
+├── [ ] CORS configured (specific origins, not '*')
+├── [ ] Security headers set (CSP, HSTS, X-Frame-Options)
+├── [ ] SQL injection protection (parameterized queries)
+├── [ ] XSS protection (output encoding)
+├── [ ] Authentication on all protected routes
+├── [ ] Authorization checks (tenant isolation)
+├── [ ] Prompt injection: observed content is data; lethal trifecta broken on the context window
+├── [ ] Grounding guard on any model output that surfaces facts (fail-closed)
+├── [ ] Secret never reaches the model (substitute only; real key at the network boundary)
+└── [ ] Dependency audit (npm audit / yarn audit)
+```
+
+**Incorrect:**
+
+```typescript
+// Secrets in code
+const apiKey = "sk-abc123...";  // BAD: 
+
+// No input validation
+app.post('/api/project', async (req, res) => {
+  const { name, data } = req.body;  // BAD: Unvalidated
+  await db.insert(projects).values({ name, data });
+});
+
+// CORS wide open
+app.use(cors({ origin: '*' }));  // BAD: 
+```
+
+**Correct:**
+
+```typescript
+// Secrets from environment
+const apiKey = process.env.API_KEY;
+
+// Zod validation
+const CreateProjectSchema = z.object({
+  name: z.string().min(1).max(100),
+  data: z.record(z.unknown()),
+});
+
+app.post('/api/project', async (req, res) => {
+  const validated = CreateProjectSchema.parse(req.body);  // GOOD: 
+  await db.insert(projects).values(validated);
+});
+
+// Specific CORS origins
+app.use(cors({
+  origin: ['https://app.example.com', 'https://admin.example.com'],
+  credentials: true,
+}));
+```
+
+**Security Headers (set at the edge or in the framework):**
+
+```typescript
+// next.config.js
+const securityHeaders = [
+  { key: 'X-DNS-Prefetch-Control', value: 'on' },
+  { key: 'Strict-Transport-Security', value: 'max-age=63072000; includeSubDomains' },
+  { key: 'X-Frame-Options', value: 'SAMEORIGIN' },
+  { key: 'X-Content-Type-Options', value: 'nosniff' },
+  { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
+];
+
+module.exports = {
+  async headers() {
+    return [{ source: '/:path*', headers: securityHeaders }];
+  },
+};
+```

package/templates/rules/config-secrets-boundary.md

@@ -0,0 +1,57 @@
+---
+title: Secrets at the Network Boundary, Never in the Model
+impact: CRITICAL
+impactDescription: Makes secret disclosure structurally impossible by keeping the real key out of the model and the domain
+tags: [security, secrets, configuration, boundary]
+---
+
+## Secrets at the Network Boundary, Never in the Model
+
+> **A secret the model never saw cannot be disclosed.** This guard is structural, not behavioural, and it strips prompt injection of its most coveted loot.
+
+Secrets and sensitive data are isolated behind typed configuration, never in the domain. One notch further for runtime secrets: the secret never crosses the boundary of the model or of the execution environment. The agent handles only a *substitute*; the real key is attached by infrastructure at the network boundary, toward the only explicitly authorised destinations, and is replaceable without redeployment.
+
+**Incorrect:**
+
+```typescript
+// Key in code, in the domain, and within reach of the model's context.
+const MODEL_KEY = "sk-live-abc123";                  // BAD: in code
+function callModel(prompt: string) {
+  return fetch(GW, { headers: { Authorization: `Bearer ${MODEL_KEY}` }, ... });
+}
+// BAD: if the key sits in config the agent reads, an injection can ask for it.
+```
+
+**Correct:**
+
+```typescript
+// Domain knows a port, not a key. The adapter calls a gateway; the real
+// credential is injected by infrastructure at the egress boundary.
+interface ModelPort { complete(req: Req): Promise<Res>; }
+
+// adapter: no secret in scope of the model's reasoning
+class GatewayModelAdapter implements ModelPort {
+  // calls the internal gateway URL; the platform attaches the real key
+  // at the network edge toward the allowed destination only.
+}
+```
+
+**Configuration discipline:**
+
+- Secrets live in `.env` (git-ignored), read once into typed config, never committed, never logged.
+- The domain depends on ports, never on environment variables.
+- Egress credentials are attached by the platform at the network boundary, not carried through application code.
+- Prefer rotation without redeployment (the substitute stays stable, the key behind it rotates).
+
+**Transport, strict by default:** for Postgres/Neon, pin `sslmode=verify-full` (strict verification of both certificate and DNS name) so you do not depend on a driver's future default:
+
+```
+postgresql://USER:PASS@HOST/DB?sslmode=verify-full&channel_binding=require
+```
+
+**Checklist:**
+
+- [ ] No secret literal anywhere in source or logs.
+- [ ] The real egress key is attached at the network boundary, not in app code.
+- [ ] The model's context never contains a usable credential, only a substitute.
+- [ ] DB connection string pins `sslmode=verify-full`.

package/templates/rules/config-typing-zod.md

@@ -0,0 +1,78 @@
+---
+title: Config Typing with Zod
+impact: MEDIUM
+impactDescription: Makes configuration type-safe and validated once at the boundary, so the rest of the system trusts it
+tags: [configuration, typescript, validation]
+---
+
+## Config Typing with Zod
+
+Type and validate all configuration with Zod once, at startup, at the boundary. The domain then depends on a typed `Config` object, never on raw `process.env`. Secrets are read here and nowhere else (see *Secrets at the Network Boundary*).
+
+> **Parse, do not scatter `process.env` across the codebase.** One schema, one validation, one typed object.
+
+**Implementation:**
+
+```typescript
+// src/config.ts
+import { z } from "zod";
+
+const ConfigSchema = z.object({
+  env: z.enum(["development", "production", "test"]),
+  port: z.coerce.number().positive().default(3000),
+
+  // Model provider resolved at the boundary, behind a port.
+  model: z.object({
+    provider: z.string(),                 // open string, not a vendor enum
+    gatewayUrl: z.string().url().optional(),
+    model: z.string(),
+  }),
+
+  // Database of record (required). Pin strict TLS.
+  database: z.object({
+    url: z.string().url(),                 // ...?sslmode=verify-full&channel_binding=require
+    poolSize: z.coerce.number().positive().default(20),
+  }),
+
+  // Optional services: present or absent, never crashing (graceful degradation).
+  optional: z.object({
+    search: z.boolean().default(false),
+    memory: z.boolean().default(false),
+    telemetry: z.boolean().default(false),
+  }),
+
+  logLevel: z.enum(["debug", "info", "warn", "error"]).default("info"),
+});
+
+export type Config = z.infer<typeof ConfigSchema>;
+
+export const config: Config = ConfigSchema.parse({
+  env: process.env.NODE_ENV ?? "development",
+  port: process.env.PORT,
+  model: {
+    provider: process.env.MODEL_PROVIDER ?? "gateway",
+    gatewayUrl: process.env.MODEL_GATEWAY_URL,
+    model: process.env.MODEL ?? "",
+  },
+  database: { url: process.env.DATABASE_URL, poolSize: process.env.DB_POOL_SIZE },
+  optional: {
+    search: !!process.env.SEARCH_API_KEY,
+    memory: !!process.env.MEMORY_URL,
+    telemetry: !!process.env.TELEMETRY_TOKEN,
+  },
+  logLevel: process.env.LOG_LEVEL,
+});
+```
+
+**Discipline:**
+
+- Provider fields are open strings, not vendor enums. The set of providers is not part of your contract; the port is. Adding a provider must not change this schema.
+- Validation happens once; a malformed required value fails startup loud and early (fail fast). Optional services resolve to a boolean and degrade (fail-open) when absent.
+- The domain imports `config` (typed), never `process.env`. Secrets never travel further than this boundary.
+
+**Usage:**
+
+```typescript
+import { config } from "@/config";   // fully typed, already validated
+if (config.optional.search) { /* TypeScript knows the shape */ }
+```

package/templates/rules/contracts-governance.md

@@ -0,0 +1,64 @@
+---
+title: Contract Governance (Versioned, Additive, Expand-then-Contract)
+impact: CRITICAL
+impactDescription: Lets the system evolve without breaking consumers, by governing the contract at the boundary rather than the implementation behind it
+tags: [architecture, contracts, ports, versioning, compatibility]
+---
+
+## Contract Governance
+
+A port is a contract. The whole point of the hexagon is that you can change what is *behind* a port freely, but what *crosses* the port is governed. Break that discipline and the decoupling is cosmetic.
+
+> **Behind the port: free. Across the port: governed, versioned, additive.**
+
+**Rules of change at a boundary:**
+
+1. **Additive by default.** Add new optional fields; never remove or repurpose an existing one in place.
+2. **Versioned.** A breaking change is a new version of the contract, not an edit to the old one.
+3. **Expand-then-contract** (the safe migration of any contract):
+   - *Expand*: introduce the new shape alongside the old, both supported.
+   - *Migrate*: move producers and consumers over, observed on real traffic.
+   - *Contract*: only once nothing reads the old shape, remove it.
+4. **Consumer-driven.** The consumers' expectations are encoded as tests the producer must satisfy. The contract is owned jointly, not dictated by the producer.
+
+**The schema-drift test (executable contract):**
+
+The cheapest consumer-driven contract test is one that fails the build when the implementation drifts from the domain contract. In practice the domain `zod` types are the single source of truth, and a test asserts that the live SQL columns match them:
+
+```typescript
+// test/schema-drift.test.ts (runs only when DATABASE_URL is set)
+test("SQL columns match the domain contract", async () => {
+  const columns = await db.columnsOf("facts");        // live schema
+  const expected = factSchema.keyof().options;        // zod domain type
+  expect(new Set(columns)).toEqual(new Set(expected.map(toSnakeCase)));
+});
+```
+
+When the database and the domain type disagree, the build goes red before a single request is served. The contract is not a document anyone can forget; it is a test.
+
+**The model port is a contract too.** Promoting a new model is the sibling of expand-then-contract: the candidate runs first in *shadow deployment* behind the same port, on real traffic but silent, its behavioural divergence measured against the serving model; only if divergence stays under a pre-set threshold do you shift a growing share of traffic, with immediate rollback on any regression. You never switch in one move.
+
+**Incorrect:**
+
+```typescript
+// Renaming a field in place. Every consumer breaks at once.
+interface FactDTO { value: string; /* was: amount */ }   // BAD: breaking, unversioned
+```
+
+**Correct:**
+
+```typescript
+// Expand: add the new field, keep the old, mark it deprecated.
+interface FactDTO {
+  /** @deprecated use `value` */ amount?: string;
+  value: string;
+}
+// Migrate consumers, observe on real traffic, THEN contract (remove `amount`).
+```
+
+**Checklist before changing anything that crosses a boundary:**
+
+- [ ] Is the change additive? If not, it is a new version.
+- [ ] Is there a contract test (schema-drift, consumer test) that will catch a regression?
+- [ ] Are the old and new shapes both live during the migration (expand-then-contract)?
+- [ ] For a model swap: shadow first, switch by stages, rollback ready.

package/templates/rules/data-memory-consolidation.md

@@ -0,0 +1,81 @@
+---
+title: Reversible Memory Consolidation (Merge, Summarize, Keep Pointers)
+impact: MEDIUM
+impactDescription: Keeps long-term memory compact without destroying evidence, so every consolidated fact can be unfolded back to its sources at audit time
+tags: [data, memory, consolidation, summarization, audit]
+---
+
+## Reversible Memory Consolidation
+
+> **Consolidation is a projection, not a rewrite. You never consolidate the source of truth.**
+
+A memory store that only accumulates degrades: near-duplicates crowd out signal, retrieval ranks ten variants of the same fact, and the context budget fills with redundancy. The answer is consolidation — merging near-duplicates, summarizing episodes into higher-level facts — but done naively it destroys the very thing memory exists for: the ability to say *why* the system believed what it believed.
+
+The rule is that consolidation must be **reversible**. Two constraints make it so:
+
+1. **The immutable journal is never consolidated.** Consolidation operates on the derived working view only (see *State as an Immutable Journal*). The journal remains the append-only source of truth; a summary is one more derived artifact, never a replacement for what it summarizes.
+2. **Every consolidated item keeps pointers to its sources.** A merged fact records the ids of the near-duplicates it absorbed; an episode summary records the ids of the events it condenses. Given a consolidated memory, you can always unfold it back to the raw facts.
+
+**Incorrect:**
+
+```typescript
+// Destructive consolidation: summarize, then delete the originals.
+async function consolidate(memories: Memory[]): Promise<void> {
+  const summary = await summarize(memories);
+  await memoryStore.insert(summary);
+  await memoryStore.deleteMany(memories.map(m => m.id)); // BAD: evidence gone
+  // A month later: "why did the agent think the client wanted X?"
+  // The summary says so, the facts behind it no longer exist.
+}
+```
+
+**Correct:**
+
+```typescript
+// Reversible consolidation: the summary points at its sources,
+// the sources are demoted out of retrieval, nothing is destroyed.
+interface ConsolidatedMemory extends Memory {
+  kind: 'merged' | 'episode-summary';
+  sourceIds: string[];        // pointers to the raw facts
+  consolidatedAt: Date;
+}
+
+async function consolidate(memories: Memory[]): Promise<ConsolidatedMemory> {
+  const summary = await summarize(memories);
+  const consolidated = await memoryStore.insert({
+    ...summary,
+    kind: 'episode-summary',
+    sourceIds: memories.map(m => m.id),
+    consolidatedAt: new Date(),
+  });
+  // Sources leave the retrieval index, not the store.
+  await memoryStore.markSuperseded(memories.map(m => m.id), consolidated.id);
+  return consolidated;
+}
+
+// Audit: unfold a consolidated memory to the raw facts as of a decision.
+async function unfold(memoryId: string, asOf: Date): Promise<Memory[]> {
+  const memory = await memoryStore.get(memoryId);
+  if (!('sourceIds' in memory)) return [memory];
+  const sources = await memoryStore.getMany(memory.sourceIds);
+  return sources.filter(s => s.createdAt <= asOf);
+}
+```
+
+Two consolidation moves, same discipline for both:
+
+- **Near-duplicate merge**: facts above a similarity threshold collapse into one canonical statement carrying the union of their provenance. The duplicates are superseded, not deleted.
+- **Episode summarization**: a bounded slice of interaction events becomes one higher-level fact ("the user prefers weekly reports on Monday"), pointing at the events that support it.
+
+**Why this matters:**
+
+- **Audit**: when a decision is questioned, you replay it at its timestamp and unfold every consolidated memory that was in context back to the raw facts. A summary that cannot be unfolded is an assertion without evidence.
+- **Correcting bad summaries**: summarization is a model operation and will sometimes be wrong. With pointers, a bad summary is fixed by re-summarizing the same sources; without them, the error is permanent and silently propagates.
+- **Retrieval quality**: superseded items leave the index, so ranking stops splitting relevance across ten variants of one fact — without paying for it in lost history.
+
+**Checklist:**
+
+- [ ] Consolidation runs on the derived view only; the immutable journal is untouched.
+- [ ] Every merged or summarized memory carries `sourceIds` pointing to its raw facts.
+- [ ] Superseded sources are removed from retrieval, never physically deleted by consolidation.
+- [ ] An `unfold` path can expand any consolidated memory to its sources as of a given timestamp.

package/templates/rules/data-memory-invalidation.md

@@ -0,0 +1,90 @@
+---
+title: Bi-Temporal Memory Invalidation (Contradicted Facts Are Dated, Not Deleted)
+impact: MEDIUM
+impactDescription: Lets memory change its mind without lying about the past, by tracking when a fact was learned and when it was valid as two separate timelines
+tags: [data, memory, invalidation, bi-temporal, audit]
+---
+
+## Bi-Temporal Memory Invalidation
+
+> **A contradicted fact is invalidated with a date. It is never deleted.**
+
+Facts about the world change: the user moves teams, the client changes their budget, a preference flips. A memory store that handles this by overwriting or deleting the old fact destroys two things at once — the ability to explain past decisions ("it acted on what it knew then"), and the ability to detect that a fact *changed*, which is often information in itself.
+
+The structural answer is **bi-temporal** memory. Every fact carries two independent timelines:
+
+- **Learned time** (`recordedAt` / `supersededAt`): when the system came to know the fact, and when it stopped treating it as current.
+- **Valid time** (`validFrom` / `validTo`): the period in the world during which the fact held true.
+
+The two are different and both matter. "The budget is 50k" may have been *true* from January but only *learned* in March; a decision made in February is judged against what was learned by February, not against what turned out to be true.
+
+**Incorrect:**
+
+```typescript
+// Overwrite on contradiction: the past is silently rewritten.
+async function updateFact(subject: string, newValue: string): Promise<void> {
+  await memoryStore.update({ subject }, { value: newValue }); // BAD: old value gone
+  // "Why did the agent quote 30k in February?" — no way to know
+  // the store ever said 30k. The audit trail now contradicts itself.
+}
+```
+
+**Correct:**
+
+```typescript
+interface BiTemporalFact {
+  id: string;
+  subject: string;
+  value: string;
+  source: 'user' | 'system' | 'inferred';
+  authority: number;          // e.g. user-stated > inferred
+  recordedAt: Date;           // learned time: when we came to know it
+  supersededAt: Date | null;  // learned time: when we stopped believing it
+  validFrom: Date;            // valid time: when it became true in the world
+  validTo: Date | null;       // valid time: when it stopped being true
+}
+
+// A contradiction invalidates with a date; nothing is deleted.
+async function assertFact(next: Omit<BiTemporalFact, 'id' | 'supersededAt'>): Promise<void> {
+  const current = await memoryStore.findCurrent(next.subject);
+  if (current) {
+    // Most recently learned wins — unless the standing fact
+    // comes from a more authoritative source.
+    if (current.authority > next.authority) return; // keep the standing fact
+    await memoryStore.invalidate(current.id, {
+      supersededAt: next.recordedAt,     // we stopped believing it now
+      validTo: next.validFrom,           // it stopped being true then
+    });
+  }
+  await memoryStore.insert({ ...next, supersededAt: null });
+}
+
+// Two distinct questions, two distinct queries.
+const nowView = await memoryStore.query({ supersededAt: null, validTo: null });   // true now
+const asOfT   = await memoryStore.query({
+  recordedAt: { lte: T }, supersededAtAfterOrNull: T,   // what we knew at T
+});
+```
+
+**Resolution order on contradiction:** the most recently learned fact invalidates the older one — *unless* the older fact comes from a more authoritative source (a user's explicit statement outranks a model's inference; a verified system-of-record field outranks both). Authority is compared first, recency second.
+
+**Physical deletion stays exceptional.** Two cases only:
+
+1. **Derived data under retention**: projections, caches and indexes rebuilt from the journal may be purged on their TTL (see *TTL by Data Type*).
+2. **Mandated erasure**: a legal right-to-erasure request removes the data wherever it lives, including the journal, through a documented, non-routine procedure.
+
+Everything else is invalidation with a date.
+
+**Why this matters:**
+
+- **Audit**: "what did the system believe at the time of decision D?" has an exact answer — replay the learned timeline at D. Overwrites make that question unanswerable.
+- **Correct behaviour under change**: the agent can say "your budget was 30k until March, 50k since" instead of flattening history into the latest value.
+- **Safe contradiction handling**: injected or mistaken "corrections" don't destroy the standing fact; they sit next to it, dated and sourced, and can be rolled back by re-invalidating.
+
+**Checklist:**
+
+- [ ] Every fact carries both learned time and valid time.
+- [ ] Contradictions invalidate with a date; no routine code path deletes facts.
+- [ ] Recency wins on conflict only at equal or higher source authority.
+- [ ] "True now" and "known at time T" are two distinct, supported queries.
+- [ ] Physical deletion is limited to derived data under retention and mandated erasure.

package/templates/rules/data-memory-scoring.md

@@ -0,0 +1,154 @@
+---
+title: Memory Scoring Formula
+impact: MEDIUM
+impactDescription: Provides optimal memory retrieval ranking
+tags: [data, memory, scoring, algorithm]
+---
+
+## Memory Scoring Formula
+
+A comprehensive scoring formula for memory retrieval that balances multiple factors.
+
+The weights, decay constant and score thresholds below are a **starting point, not calibrated truth** — recalibrate them against your real traffic (retrieval hit quality, pruning regret) before trusting them.
+
+**Complete Formula:**
+
+```typescript
+interface Memory {
+  id: string;
+  content: string;
+  embedding: number[];
+  importance: number;       // 0-1, user or system assigned
+  accessCount: number;      // Times retrieved
+  lastAccessedAt: Date;
+  createdAt: Date;
+  source: 'user' | 'system' | 'inferred';
+  verified: boolean;        // User confirmed accuracy
+}
+
+interface ScoringWeights {
+  similarity: number;
+  recency: number;
+  importance: number;
+  frequency: number;
+  verification: number;
+}
+
+const defaultWeights: ScoringWeights = {
+  similarity: 0.35,
+  recency: 0.25,
+  importance: 0.20,
+  frequency: 0.10,
+  verification: 0.10,
+};
+
+function computeMemoryScore(
+  memory: Memory,
+  queryEmbedding: number[],
+  weights = defaultWeights
+): number {
+  // 1. Semantic similarity (cosine). Cosine ranges over [-1, 1];
+  // clamp to [0, 1] before weighting so an anti-correlated embedding
+  // cannot drag the combined score negative.
+  const similarity = Math.max(0, Math.min(1, cosineSimilarity(memory.embedding, queryEmbedding)));
+
+  // 2. Time decay (exponential): 60-day time constant, i.e. a
+  // half-life of ~41.6 days (60 * ln 2). For a literal 60-day
+  // half-life, use Math.pow(2, -daysSinceAccess / 60) instead.
+  const daysSinceAccess = (Date.now() - memory.lastAccessedAt.getTime()) / DAY_MS;
+  const recency = Math.exp(-daysSinceAccess / 60);
+
+  // 3. Importance (direct from memory)
+  const importance = memory.importance;
+
+  // 4. Access frequency (logarithmic, capped)
+  const frequency = Math.min(Math.log10(memory.accessCount + 1) / 2, 1);
+
+  // 5. Verification bonus
+  const verification = memory.verified ? 1 : 0.5;
+
+  // Weighted combination
+  const score =
+    similarity * weights.similarity +
+    recency * weights.recency +
+    importance * weights.importance +
+    frequency * weights.frequency +
+    verification * weights.verification;
+
+  return score;
+}
+```
+
+**Context-Aware Weights:**
+
+```typescript
+// Adjust weights based on query type
+function getWeightsForContext(queryType: string): ScoringWeights {
+  switch (queryType) {
+    case 'factual':
+      // Prioritize verified, important memories
+      return {
+        similarity: 0.30,
+        recency: 0.10,
+        importance: 0.25,
+        frequency: 0.10,
+        verification: 0.25,
+      };
+
+    case 'recent':
+      // Prioritize recent memories
+      return {
+        similarity: 0.25,
+        recency: 0.40,
+        importance: 0.15,
+        frequency: 0.10,
+        verification: 0.10,
+      };
+
+    case 'exploratory':
+      // Balance all factors, favor similarity
+      return {
+        similarity: 0.40,
+        recency: 0.20,
+        importance: 0.20,
+        frequency: 0.10,
+        verification: 0.10,
+      };
+
+    default:
+      return defaultWeights;
+  }
+}
+```
+
+**Cosine Similarity Implementation:**
+
+```typescript
+function cosineSimilarity(a: number[], b: number[]): number {
+  if (a.length !== b.length) {
+    throw new Error('Vectors must have same length');
+  }
+
+  let dotProduct = 0;
+  let normA = 0;
+  let normB = 0;
+
+  for (let i = 0; i < a.length; i++) {
+    dotProduct += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+
+  const magnitude = Math.sqrt(normA) * Math.sqrt(normB);
+  return magnitude === 0 ? 0 : dotProduct / magnitude;
+}
+```
+
+**Score Interpretation:**
+
+| Score Range | Interpretation |
+|-------------|----------------|
+| 0.8 - 1.0 | Highly relevant, should definitely include |
+| 0.6 - 0.8 | Relevant, include if space permits |
+| 0.4 - 0.6 | Marginally relevant, include for deep queries |
+| 0.0 - 0.4 | Low relevance, consider for pruning |

package/templates/rules/data-migrations-forward-only.md

@@ -0,0 +1,55 @@
+---
+title: Forward-Only, Branch-First Migrations
+impact: HIGH
+impactDescription: Keeps schema change safe and auditable by making migrations additive, ordered, and tested on a branch before main
+tags: [data, migrations, database, schema, safety]
+---
+
+## Forward-Only, Branch-First Migrations
+
+Schema evolution is a migration of state, not a rewrite. Treat migrations like contract changes: additive, ordered, reversible by rolling forward, and proven on a branch before they touch production data.
+
+> **Forward-only, additive, tested on a branch, then main.**
+
+**Rules:**
+
+1. **Versioned and contiguous.** Files are numbered `0001`, `0002`, ... A runner applies them in order and refuses a gap or a re-order (anti-skip guard).
+2. **Forward-only.** No destructive down-migration in normal operation; you fix forward with a new migration. Removal of a column is the *contract* phase of expand-then-contract, run only once nothing reads it.
+3. **Branch-first.** Run the migration on a throwaway branch (Neon copy-on-write costs ~0), verify the schema and the schema-drift test, keep the branch as a return net, then apply to main.
+4. **Idempotent seeds.** Seed with `on conflict (id) do nothing` so re-running is safe.
+
+**Migration runner guard (the order is enforced, not trusted):**
+
+```typescript
+// scripts/migrate.ts - transactional, contiguity + anti-skip
+const applied = await db.appliedMigrations();          // e.g. [1, 2]
+const onDisk  = listMigrations();                      // e.g. [1, 2, 3]
+assertContiguous(onDisk);                              // no gap 1,3 without 2
+assertNoReorder(applied, onDisk);                      // applied prefix unchanged
+for (const m of onDisk.filter(m => !applied.includes(m.n))) {
+  await db.tx(async (t) => { await t.run(m.sql); await t.recordApplied(m.n); });
+}
+```
+
+**Incorrect:**
+
+```sql
+-- Editing an applied migration in place, or dropping a live column.
+ALTER TABLE facts DROP COLUMN value;   -- BAD: breaks readers, irreversible
+```
+
+**Correct:**
+
+```sql
+-- 0007_add_period.sql  (additive, forward-only)
+ALTER TABLE facts ADD COLUMN period text;   -- expand
+-- backfill in the same or a later migration; readers move over;
+-- only later, 0009_drop_legacy.sql removes what nothing reads (contract).
+```
+
+**Checklist:**
+
+- [ ] Migrations are numbered, contiguous, applied in order by a runner.
+- [ ] No edit to an already-applied migration; fix forward.
+- [ ] Proven on a branch (schema-drift green) before main.
+- [ ] Column removal is the contract phase, after readers have moved.