runward 0.6.0

package/templates/rules/data-orphan-cleanup.md

@@ -0,0 +1,142 @@
+---
+title: Orphan Data Cleanup
+impact: MEDIUM
+impactDescription: Prevents data bloat from orphaned records
+tags: [data, cleanup, maintenance, integrity]
+---
+
+## Orphan Data Cleanup
+
+Orphaned records waste storage and can cause bugs. Regular cleanup is essential.
+
+**Common Orphan Types:**
+
+| Orphan Type | Detection | Action |
+|-------------|-----------|--------|
+| Project without owner | Cron weekly | Notify admin, archive after 30d |
+| Messages without session | Cron daily | Anonymize + archive |
+| Files (S3) without DB ref | Cron monthly | Quarantine then delete |
+| Broken DB relationships | Cron weekly | Rebuild or delete |
+| Unused embeddings | Cron monthly | Delete |
+
+**Implementation:**
+
+```typescript
+// Orphan detection and cleanup service
+class OrphanCleanupService {
+  async findOrphanProjects(): Promise<Project[]> {
+    return db.projects.findMany({
+      where: {
+        OR: [
+          { ownerId: null },
+          { owner: { deletedAt: { not: null } } },
+        ],
+        orphanedAt: null,  // Not already marked
+      },
+    });
+  }
+
+  async handleOrphanProjects() {
+    const orphans = await this.findOrphanProjects();
+
+    for (const project of orphans) {
+      // Mark as orphaned, set deadline
+      await db.projects.update({
+        where: { id: project.id },
+        data: {
+          orphanedAt: new Date(),
+          archiveDeadline: addDays(new Date(), 30),
+        },
+      });
+
+      // Notify admins
+      await notifyAdmins('orphan_project', {
+        projectId: project.id,
+        projectName: project.name,
+        archiveDeadline: addDays(new Date(), 30),
+      });
+    }
+
+    logger.info('Orphan projects processed', { count: orphans.length });
+  }
+
+  async archiveExpiredOrphans() {
+    const expired = await db.projects.findMany({
+      where: {
+        archiveDeadline: { lt: new Date() },
+        archivedAt: null,
+      },
+    });
+
+    for (const project of expired) {
+      await this.archiveProject(project);
+    }
+  }
+
+  async findOrphanFiles(): Promise<string[]> {
+    // List all S3 files
+    const s3Files = await s3.listObjects({ Bucket: 'uploads' });
+
+    // Get all referenced files from DB
+    const referencedFiles = await db.files.findMany({
+      select: { s3Key: true },
+    });
+    const referencedSet = new Set(referencedFiles.map(f => f.s3Key));
+
+    // Find orphans
+    return s3Files
+      .filter(f => !referencedSet.has(f.Key))
+      .map(f => f.Key);
+  }
+
+  async cleanupOrphanFiles() {
+    const orphans = await this.findOrphanFiles();
+
+    // Move to quarantine first (safety)
+    for (const key of orphans) {
+      await s3.copyObject({
+        CopySource: `uploads/${key}`,
+        Bucket: 'uploads-quarantine',
+        Key: key,
+      });
+    }
+
+    logger.info('Orphan files quarantined', { count: orphans.length });
+
+    // Delete from main bucket after 30 days in quarantine
+    // (separate cron job)
+  }
+}
+
+// Schedule cleanup jobs
+cron.schedule('0 2 * * 0', () => orphanService.handleOrphanProjects());  // Weekly
+cron.schedule('0 3 * * *', () => orphanService.archiveExpiredOrphans());  // Daily
+cron.schedule('0 4 1 * *', () => orphanService.cleanupOrphanFiles());     // Monthly
+```
+
+**Database Integrity Check:**
+
+```typescript
+async function checkDatabaseIntegrity() {
+  const issues: IntegrityIssue[] = [];
+
+  // Check foreign key references
+  const brokenRefs = await db.$queryRaw`
+    SELECT m.id, m.session_id
+    FROM messages m
+    LEFT JOIN sessions s ON m.session_id = s.id
+    WHERE s.id IS NULL
+  `;
+
+  if (brokenRefs.length > 0) {
+    issues.push({
+      type: 'broken_reference',
+      table: 'messages',
+      count: brokenRefs.length,
+      ids: brokenRefs.map(r => r.id),
+    });
+  }
+
+  return issues;
+}
+```

package/templates/rules/data-ttl-types.md

@@ -0,0 +1,100 @@
+---
+title: TTL by Data Type
+impact: MEDIUM
+impactDescription: Ensures proper data lifecycle management and compliance
+tags: [data, lifecycle, compliance, ttl]
+---
+
+## TTL by Data Type
+
+Different data types require different retention policies. Define TTLs at the schema level.
+
+**Example TTLs:**
+
+> The durations below are **examples — set actual retention periods with legal counsel; they are jurisdiction-specific** (statutory retention duties, storage-limitation principles, sector rules).
+
+| Data Type | TTL | Action at Expiration |
+|-----------|-----|---------------------|
+| Active chat sessions | Session duration | Archive + summarize |
+| Archived sessions | 2 years | Pseudonymize then delete |
+| Active projects | Project duration | Archive |
+| Completed projects | 5 years | Pseudonymize personal data |
+| Agent memories | Progressive decay | Prune if score < threshold |
+| Audit logs | 5 years (legal) | Cold archive |
+| Technical logs | 90 days | Delete |
+| API tokens | 90 days | Revoke |
+| Password reset | 1 hour | Delete |
+
+**Implementation:**
+
+```typescript
+// Schema with TTL metadata
+interface DataSchema {
+  type: string;
+  ttlDays: number | null;  // null = never expires
+  expirationAction: 'delete' | 'archive' | 'pseudonymize';
+}
+
+const dataSchemas: Record<string, DataSchema> = {
+  chatSession: { type: 'chatSession', ttlDays: null, expirationAction: 'archive' },
+  archivedSession: { type: 'archivedSession', ttlDays: 730, expirationAction: 'pseudonymize' },
+  auditLog: { type: 'auditLog', ttlDays: 1825, expirationAction: 'archive' },
+  technicalLog: { type: 'technicalLog', ttlDays: 90, expirationAction: 'delete' },
+  memory: { type: 'memory', ttlDays: null, expirationAction: 'delete' },  // Score-based
+};
+
+// Cleanup cron job
+async function runDataCleanup() {
+  for (const [type, schema] of Object.entries(dataSchemas)) {
+    if (!schema.ttlDays) continue;
+
+    const cutoff = new Date(Date.now() - schema.ttlDays * 24 * 60 * 60 * 1000);
+
+    switch (schema.expirationAction) {
+      case 'delete':
+        await db.deleteWhere(type, { createdAt: { lt: cutoff } });
+        break;
+      case 'archive':
+        await db.archiveWhere(type, { createdAt: { lt: cutoff } });
+        break;
+      case 'pseudonymize':
+        await db.pseudonymizeWhere(type, { createdAt: { lt: cutoff } });
+        break;
+    }
+
+    logger.info(`Data cleanup completed for ${type}`, { cutoff, action: schema.expirationAction });
+  }
+}
+
+// Run daily
+cron.schedule('0 3 * * *', runDataCleanup);
+```
+
+**Pseudonymization Pattern (this is NOT anonymization):**
+
+A hashed email is still personal data: the hash is a stable pseudonym that can be linked back to the person (dictionary attack on known addresses, or simply joining on the same hash elsewhere). Data-protection regimes such as the GDPR treat pseudonymized data as personal data, with all obligations attached. True **anonymization** is irreversible — outright deletion of identifying fields, or aggregation into counts that no longer describe an individual.
+
+```typescript
+// Pseudonymization: reversible in principle, still personal data.
+async function pseudonymizeRecord(record: UserData): Promise<PseudonymizedData> {
+  return {
+    ...record,
+    email: hashEmail(record.email),  // stable pseudonym, NOT anonymous
+    name: null,
+    phone: null,
+    address: null,
+    // Keep non-personal fields for analytics
+    createdAt: record.createdAt,
+    projectCount: record.projectCount,
+  };
+}
+
+// Anonymization: irreversible. Either delete the record outright, or
+// keep only aggregates that no longer describe an individual.
+async function anonymizeIntoAggregates(records: UserData[]): Promise<void> {
+  await db.analytics.increment('projects_completed', sum(records.map(r => r.projectCount)));
+  await db.deleteMany(records.map(r => r.id));  // individual rows are gone
+}
+```
+
+Decide per field, with legal counsel, whether pseudonymization is enough (data stays in scope of the regulation) or true anonymization is required.

package/templates/rules/eval-loop.md

@@ -0,0 +1,52 @@
+---
+title: Evaluation Loop (Test + Evaluate, Hold-out, Anchored Judge)
+impact: CRITICAL
+impactDescription: Gives a non-deterministic system a trustworthy way to detect behavioural regressions without letting it optimise its own grader
+tags: [evaluation, testing, llm, quality, governance]
+---
+
+## Evaluation Loop
+
+> **A deterministic system is tested. An agentic system is tested *and* evaluated.**
+
+The code around the agent is verified like any software (unit, integration, contract). The agent's behaviour is non-deterministic, so it needs a second instrument: an evaluation rubric replayed over scenarios, scored over time.
+
+**Two distinct instruments, never confused:**
+
+| | Test | Evaluation |
+|---|---|---|
+| Subject | Deterministic code | Agent behaviour |
+| Verdict | Pass / fail | Score on a rubric |
+| Guarantee | Hard | Behavioural signal |
+| Owns | Safety, authorisation, schema, idempotency | Faithfulness, clarity, abstention quality |
+
+**Abstention is scored.** For a grounded system, refusing to invent a figure counts as much as recalling one. A hallucinated number where the agent should have abstained is the worst outcome, scored zero, even if the rest is perfect.
+
+**The hold-out is non-manipulable.** A naive closed loop that optimises the judge's score drifts toward what flatters the judge without improving real quality. What makes self-tuning safe is a guard the optimiser never sees: a hold-out with verifiable ground truth that triggers a rollback when the hallucination rate climbs. The hold-out is only valid where ground truth is verifiable; for purely subjective quality, the net is a human sample and the self-tuning envelope stays narrow.
+
+**The judge is anchored.** The model that scores behavioural quality is frozen in version; on any judge change you replay an anchoring set to recalibrate, otherwise the quality series becomes incomparable in silence. The judge covers only irreducible behavioural quality. The hard floor (is the figure exactly the one in the store, is the source the right one) stays deterministic, compared directly to the store, never handed to the judge.
+
+**No chorus of verifiers replaces a deterministic guard.** Stacking fallible LLM checkers that re-read each other does not manufacture a hard property: their errors correlate (shared data, shared blind spots), an adversarial input that fools one fools the chorus, and each check is one more slow, costly inference where a deterministic control is free and certain. Deterministic for what admits a guarantee; judge only for behavioural quality; always under the hold-out.
+
+**The loop is open at the action boundary.** It produces signals and recommendations. Acting on them goes through a bounded, audited tuning envelope or a human decision, never an autonomous rewrite of the agent.
+
+**Eval runbook (per scenario):**
+
+```
+Add     describe the multi-turn conversation, the final question,
+        the expected and forbidden terms, the capability targeted.
+Run     replay the turns in order against the current system,
+        ask the final question, compare to expected/forbidden terms.
+Score   apply the rubric, track the score per capability over time
+        to catch behavioural regressions.
+```
+
+**Continuous faithfulness metric (monitoring, not gating):** alongside the deterministic guard, run a faithfulness metric of the RAGAS / FActScore family over a traffic sample: decompose each synthesis into atomic claims, verify each against the served facts and their source, aggregate into a per-request score and a time series. The guard blocks; the metric alerts. They are complementary.
+
+**Checklist:**
+
+- [ ] Tests and evaluation are separate; safety lives in tests, not in the rubric.
+- [ ] Abstention is a scored capability.
+- [ ] A non-manipulable hold-out with verifiable ground truth gates regressions.
+- [ ] The judge is version-anchored; the deterministic floor never goes to the judge.
+- [ ] Acting on eval signals is bounded-and-audited or human, never autonomous.

package/templates/rules/frontier-deterministic-boundary.md

@@ -0,0 +1,91 @@
+---
+title: Deterministic Boundary of the Model
+impact: CRITICAL
+impactDescription: Keeps every fact, figure and decision that can be checked out of the model, so the system is verifiable and cannot hallucinate load-bearing values
+tags: [architecture, llm, frontier, grounding, safety, determinism]
+---
+
+## Deterministic Boundary of the Model
+
+> **The model writes prose. The program owns the facts.**
+> Anything that can be retrieved, computed, validated or decided deterministically must live in code, never in the model's free generation. The model is rented and non-deterministic; the boundary around it is owned and tested.
+
+This is the strongest form of the LLM Boundary Principle: not only move deterministic *logic* out (routing, classification), but move deterministic *truth* out. The model is allowed to phrase, summarise and connect. It is never the source of a number, a citation, a price, a date, or an authorisation.
+
+**Why structured outputs are not enough:** constrained decoding and JSON schema guarantee the *shape* of the output, never its *meaning*. A model can emit a perfectly valid JSON number that is invented. Shape validation and truth validation are two different jobs.
+
+**Incorrect:**
+
+```typescript
+// The model is asked to "report the figures". It will, including ones it invents.
+const answer = await model.complete(`
+  Summarise the company's AI budget from these notes: ${notes}
+  Give exact percentages and the source.
+`);
+// BAD: Any % in `answer` is the model's word, unverifiable, potentially hallucinated.
+```
+
+**Correct (data-to-text / slot-filling):**
+
+```typescript
+// 1. Facts come from a structured store, each with value, unit, period, source.
+const facts = await portFacts.query({ topic, edition });   // deterministic
+
+// 2. The model writes the narrative and emits SLOTS, never raw numbers.
+//    Prompt: "Refer to a served fact as {f0}, {f1}... Never write a figure yourself."
+const draft = await model.complete(buildPrompt(question, facts));
+
+// 3. The program substitutes value + unit + period into each slot.
+const answer = fillSlots(draft, facts);                    // deterministic
+
+// 4. A guard rejects the response if any number in it is not grounded in served facts.
+assertGrounded(answer, facts);                             // fail-closed
+```
+
+**The grounding guard (executable specification of the boundary):**
+
+```typescript
+// Extract numbers that are not part of a word/identifier, normalise FR decimals.
+const NUMBER = /(?<![\p{L}\d-])\d+(?:[.,]\d+)?/gu;
+
+// Grounded set = fact values ∪ numbers appearing in served fact labels ∪ plausible years.
+function groundedSet(facts: Pick<Fact, "value" | "indicator">[]): Set<string> {
+  const set = new Set<string>();
+  for (const f of facts) {
+    set.add(normalise(f.value));
+    for (const n of f.indicator.match(NUMBER) ?? []) set.add(normalise(n));
+  }
+  return set;
+}
+
+// Reject any figure in the synthesis that is not in the grounded set (years excepted).
+export function assertGrounded(text: string, facts: Pick<Fact, "value" | "indicator">[]): void {
+  const grounded = groundedSet(facts);
+  for (const n of text.match(NUMBER) ?? []) {
+    const v = normalise(n);
+    if (!grounded.has(v) && !isPlausibleYear(v)) {
+      throw new GroundingError(`Ungrounded figure in synthesis: ${n}`);
+    }
+  }
+}
+```
+
+**Layered defence, by maturity of the model wiring:**
+
+| Stage | Mechanism | Guarantee |
+|-------|-----------|-----------|
+| Floor | Guard checks every figure against the served facts (value ∪ label numbers ∪ years) | No invented number reaches the user |
+| Wired with structured outputs | Model emits `{fN}` slots, program substitutes value+unit+period | Attribution is exact (AIS: Attributable to Identified Sources) |
+| Monitoring | Faithfulness metric (RAGAS / FActScore family) over a traffic sample | Drift in narrative faithfulness is measured and alerted, not blocked |
+
+The guard **guarantees and blocks** ("can we serve this?"). The metric **measures and alerts** ("how faithful is the prose over time?"). They are complementary, never redundant.
+
+**Boundary checklist for any feature that surfaces facts:**
+
+- [ ] Every load-bearing value comes from a typed store, not from the model.
+- [ ] The model's output passes a grounding guard before it reaches a user.
+- [ ] The guard **fails closed**: on doubt it rejects, it does not pass through.
+- [ ] Abstention is a first-class answer: "not in the corpus" beats a plausible guess.
+- [ ] The guard has unit tests that feed realistic facts *with their labels* (the spec is executable).
+
+**Where this sits in the Runward method:** the deterministic boundary is the practical form of the guiding principle — the deterministic stays out of the model. It is also a security control: a hallucinated figure is an integrity failure, not just a quality one.

package/templates/rules/hexa-adapter-pattern.md

@@ -0,0 +1,85 @@
+---
+title: New Feature = New Adapter
+impact: HIGH
+impactDescription: Keeps core business logic clean and external integrations isolated
+tags: [architecture, hexagonal, adapters, integration]
+---
+
+## New Feature = New Adapter
+
+When adding a new external integration, always create a new adapter. Never mix external service logic into core.
+
+**The Rule:**
+
+> **New external service → New adapter implementing existing or new port**
+
+**Incorrect:**
+
+```typescript
+// Business logic mixed with external service
+// core/application/analyze-project.ts
+import { WebSearchClient } from 'web-search';  // BAD: External import in core
+
+export class AnalyzeProjectUseCase {
+  async execute(projectId: string) {
+    // BAD: Direct external service usage in core
+    const web-search = new WebSearchClient(process.env.SEARCH_API_KEY);
+    const searchResults = await web-search.search(query);
+    // ...
+  }
+}
+```
+
+**Correct:**
+
+```typescript
+// 1. Define port in core
+// core/ports/out/search-gateway.port.ts
+export interface SearchGateway {
+  search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+}
+
+// 2. Use case depends on port (interface), not implementation
+// core/application/analyze-project.ts
+export class AnalyzeProjectUseCase {
+  constructor(private searchGateway: SearchGateway) {}
+
+  async execute(projectId: string) {
+    const searchResults = await this.searchGateway.search(query);
+    // ...
+  }
+}
+
+// 3. Adapter implements port
+// adapters/secondary/search/web-search.adapter.ts
+import { WebSearchClient } from 'web-search';
+import { SearchGateway, SearchResult } from '@/core/ports/out/search-gateway.port';
+
+export class WebSearchAdapter implements SearchGateway {
+  private client: WebSearchClient;
+
+  constructor(apiKey: string) {
+    this.client = new WebSearchClient(apiKey);
+  }
+
+  async search(query: string): Promise<SearchResult[]> {
+    const results = await this.client.search(query);
+    return results.map(this.mapToSearchResult);
+  }
+}
+
+// 4. Alternative adapter for testing or different provider
+// adapters/secondary/search/mock.adapter.ts
+export class MockSearchAdapter implements SearchGateway {
+  async search(query: string): Promise<SearchResult[]> {
+    return [{ title: 'Mock result', url: 'https://example.com' }];
+  }
+}
+```
+
+**Benefits:**
+
+- Core is testable without external services
+- Easy to swap providers (the search provider → another provider)
+- Clear contracts between layers
+- External service changes don't affect core logic

package/templates/rules/hexa-architecture.md

@@ -0,0 +1,84 @@
+---
+title: Hexagonal Architecture Structure
+impact: HIGH
+impactDescription: Enables testability, maintainability, and clean dependency management
+tags: [architecture, hexagonal, structure, testing]
+---
+
+## Hexagonal Architecture Structure
+
+Organize code into layers with clear boundaries. Dependencies point inward. External services are adapters.
+
+**Incorrect:**
+
+```typescript
+// Everything mixed together
+src/
+├── api/
+│   └── projects.ts      // Contains business logic + DB + LLM calls
+├── utils/
+│   └── helpers.ts       // Random functions
+└── types.ts             // All types in one file
+```
+
+**Correct:**
+
+```
+src/
+├── core/                    # UNTOUCHABLE - Pure business logic
+│   ├── domain/              # Entities, value objects, domain events
+│   │   ├── project.ts
+│   │   └── user.ts
+│   ├── application/         # Use cases (orchestration)
+│   │   ├── create-project.ts
+│   │   └── analyze-project.ts
+│   └── ports/               # Interfaces (contracts)
+│       ├── in/              # Primary ports (how app is used)
+│       │   └── project-service.port.ts
+│       └── out/             # Secondary ports (what app needs)
+│           ├── project-repository.port.ts
+│           └── llm-gateway.port.ts
+│
+├── adapters/
+│   ├── primary/             # How the outside world calls us
+│   │   ├── rest/            # REST API
+│   │   ├── graphql/         # GraphQL API
+│   │   └── cli/             # CLI commands
+│   └── secondary/           # How we call the outside world
+│       ├── database/        # Postgres, graph store adapters
+│       ├── llm/             # model provider adapters
+│       └── external/        # Third-party APIs
+│
+└── infrastructure/
+    ├── config/              # Zod-typed configuration
+    ├── middleware/          # Request middleware
+    └── observability/       # Logging, metrics, tracing
+```
+
+**Port Example:**
+
+```typescript
+// core/ports/out/llm-gateway.port.ts
+export interface LLMGateway {
+  complete(prompt: string, options: CompletionOptions): Promise<string>;
+  embed(text: string): Promise<number[]>;
+}
+
+// adapters/secondary/model/provider.adapter.ts
+export class ModelAdapter implements LLMGateway {
+  async complete(prompt: string, options: CompletionOptions): Promise<string> {
+    const response = await this.client.messages.create({...});
+    return response.content[0].text;
+  }
+}
+```
+
+**Dependency Rule:**
+
+```
+External World → Adapters → Ports → Core Domain
+                    ↑          ↓
+              (implements)  (depends on)
+```
+
+Core never imports from adapters. Adapters implement ports defined in core.

package/templates/rules/hexa-move-deterministic-out.md

@@ -0,0 +1,93 @@
+---
+title: Move the Deterministic out of the Model
+impact: CRITICAL
+impactDescription: Reduces LLM costs and latency by moving deterministic logic out of LLM calls
+tags: [architecture, llm, cost-optimization, performance]
+---
+
+## LLM Boundary Principle
+
+> **Everything that can be deterministic, testable, and cacheable must be moved out of the LLM.**
+
+LLMs are expensive, slow, and non-deterministic. Move everything possible to code.
+
+**Incorrect:**
+
+```typescript
+// LLM does classification AND response
+const response = await llm.complete({
+  prompt: `
+    Analyze this message and determine:
+    1. Is it casual, task-oriented, or complex?
+    2. What data sources are needed?
+    3. Generate the response.
+
+    Message: ${userMessage}
+  `
+});
+// BAD: Pays full LLM cost for classification
+// BAD: Non-deterministic classification
+// BAD: Can't test classification logic
+```
+
+**Correct:**
+
+```typescript
+// Step 1: Deterministic classification (regex)
+const regexResult = classifyWithRegex(userMessage);
+if (regexResult.confidence >= 0.6) {
+  complexity = regexResult;  // $0, ~1ms
+} else {
+  // Step 2: Cheap LLM classification (Fast)
+  complexity = await classifyWithFastModel(userMessage);  // ~$0.0003, ~100ms
+}
+
+// Step 3: Deterministic routing
+const model = selectModel(complexity);
+const dataSources = selectDataSources(complexity);
+
+// Step 4: Only use expensive LLM for actual generation
+const response = await llm.complete({
+  model,
+  prompt: buildPrompt(userMessage, dataSources),
+});
+```
+
+**What to Move Out:**
+
+| Logic | Method | Savings |
+|-------|--------|---------|
+| Request classification | Regex + fallback Fast | -40% classification cost |
+| Model selection | Deterministic rules | -55% average cost |
+| Memory source selection | Router by complexity | -76% latency |
+| Format validation | Zod schemas | $0 (vs LLM validation) |
+| Error detection | Pattern matching | Instant feedback |
+
+**Implementation Pattern:**
+
+```typescript
+// The LLM should only do what requires intelligence
+interface LLMBoundary {
+  // OUT: Deterministic pre-processing
+  classify(message: string): ComplexityLevel;
+  selectModel(complexity: ComplexityLevel): Model;
+  selectSources(complexity: ComplexityLevel): DataSource[];
+  buildPrompt(message: string, context: Context): string;
+
+  // IN: Actual LLM call
+  generate(prompt: string, model: Model): Promise<string>;
+
+  // OUT: Deterministic post-processing
+  validateOutput(output: string, schema: ZodSchema): Result;
+  formatResponse(result: Result): Response;
+}
+```
+
+**Testing Benefits:**
+
+- Classification logic: 100% unit testable
+- Routing logic: 100% unit testable
+- Only generation needs integration tests
+- Faster test suite, more reliable CI
+
+**The stronger form: move deterministic *truth* out, not only deterministic *logic*.** This rule moves classification, routing and validation out of the model. Its critical extension is to also keep load-bearing facts and figures out of the model's free generation. See `frontier-deterministic-boundary`.

package/templates/rules/hexa-recommended-stack.md

@@ -0,0 +1,33 @@
+---
+title: Stack Posture (Sober Default plus Trigger), Not a Fixed Stack
+impact: MEDIUM
+impactDescription: Replaces a frozen product stack with a portable rule for choosing technology by evidence, so the rule does not age with any vendor
+tags: [architecture, stack, decision, portability]
+---
+
+## Stack Posture, Not a Fixed Stack
+
+A method describes functions, never products, so it ages slowly. This rule follows the same discipline: it does not prescribe a vendor stack. It prescribes how to choose one.
+
+> **Start with the smallest stack that proves value on real traffic. Cross a frontier (new service, new database, new provider) only on an objective trigger.**
+
+**Default posture at the floor:**
+
+| Concern | Sober default | Cross the frontier when (trigger) |
+|---|---|---|
+| Language | One typed language for the core, chosen by the team's fluency and the ecosystem | A second runtime earns a measured, isolated need (e.g. a Python sidecar for OCR/NLP) |
+| Topology | Modular monolith, single process | A real, measured reason to split a service (independent scaling, isolation, team boundary) |
+| Model | One provider behind a `ModelPort`, ideally via a gateway | Availability fallback, or a validated promotion in shadow deployment |
+| Persistence | One relational store (Postgres) for facts; vectors in the same store (pgvector) | Volume that overflows the single store; a real graph traversal becomes central |
+| State / scale | In-process, single instance | Horizontal scaling needed -> externalise state first |
+| Async | Inline | A workload genuinely needs scheduling or backpressure |
+
+**How to record a stack choice:** each line above is a decision with a default and a trigger. When a trigger fires, the choice is made in an ADR with the options and a preference order, not improvised. Until the trigger fires, you do not pre-build and you do not re-debate.
+
+**What does not belong in the core, whatever the stack:**
+
+- No vendor SDK imported from the domain (model, database, search are adapters).
+- No framework owning your control flow that you cannot see through; prefer thin abstractions you own.
+- No optional service that crashes the app when absent.
+
+When you pin a concrete stack for a mission, record it as an illustration of the method, not as a stack to copy.