# Rule catalog The 64 craft rules, each mapped to phases and an OWASP ASI risk (source: `runward rules --json`). ## Background Job Guardrails (Retry, Idempotency, Bounded Concurrency, Job Observability) - **Slug**: `async-job-guardrails` - **Impact**: HIGH - **Phases**: govern - **ASI**: ASI08 The four non-negotiables of any background job — bounded retry per step, idempotency under concurrency, capped and partitioned concurrency, and queue lag plus failure rate as first-class metrics ## Post-Turn Pipeline (Keep the Interactive Turn Thin) - **Slug**: `async-post-turn-pipeline` - **Impact**: HIGH - **Phases**: advisory - **ASI**: — 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 ## Scheduled Maintenance (The Cron Updates and Cools, It Never Destroys Truth) - **Slug**: `async-scheduled-maintenance` - **Impact**: MEDIUM - **Phases**: advisory - **ASI**: — 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 ## Prompt Cache Stability (a Cost Lever, Provider-Specific) - **Slug**: `cache-three-tier-architecture` - **Impact**: MEDIUM - **Phases**: advisory - **ASI**: — Cuts input-token cost when a provider bills cached prefixes cheaper, by keeping the stable part of the prompt byte-identical across requests ## Day-Zero Project Setup Checklist - **Slug**: `checklist-day-zero-project` - **Impact**: CRITICAL - **Phases**: advisory - **ASI**: — Starts a project on the foundation that prevents costly refactors, with the core engineering disciplines wired from the first commit ## Pre-Production Observability Checklist - **Slug**: `checklist-pre-production-observability` - **Impact**: HIGH - **Phases**: advisory - **ASI**: — Ensures you can monitor and debug production issues ## Pre-Production Performance Checklist - **Slug**: `checklist-pre-production-performance` - **Impact**: HIGH - **Phases**: advisory - **ASI**: — Ensures application performs well under production load ## Pre-Production Resilience Checklist - **Slug**: `checklist-pre-production-resilience` - **Impact**: CRITICAL - **Phases**: advisory - **ASI**: ASI08 Ensures application handles failures gracefully in production ## Pre-Production Security Checklist - **Slug**: `checklist-pre-production-security` - **Impact**: CRITICAL - **Phases**: advisory - **ASI**: ASI02, ASI03, ASI06 Ensures security requirements are met before production deployment ## Secrets at the Network Boundary, Never in the Model - **Slug**: `config-secrets-boundary` - **Impact**: CRITICAL - **Phases**: floor, govern - **ASI**: ASI03, ASI10 Makes secret disclosure structurally impossible by keeping the real key out of the model and the domain ## Config Typing with Zod - **Slug**: `config-typing-zod` - **Impact**: MEDIUM - **Phases**: advisory - **ASI**: — Makes configuration type-safe and validated once at the boundary, so the rest of the system trusts it ## Contract Governance (Versioned, Additive, Expand-then-Contract) - **Slug**: `contracts-governance` - **Impact**: CRITICAL - **Phases**: architect - **ASI**: ASI04, ASI07 Lets the system evolve without breaking consumers, by governing the contract at the boundary rather than the implementation behind it ## Reversible Memory Consolidation (Merge, Summarize, Keep Pointers) - **Slug**: `data-memory-consolidation` - **Impact**: MEDIUM - **Phases**: advisory - **ASI**: — Keeps long-term memory compact without destroying evidence, so every consolidated fact can be unfolded back to its sources at audit time ## Bi-Temporal Memory Invalidation (Contradicted Facts Are Dated, Not Deleted) - **Slug**: `data-memory-invalidation` - **Impact**: MEDIUM - **Phases**: advisory - **ASI**: — 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 ## Memory Carries Provenance; an Untrusted Write Cannot Act Unreviewed - **Slug**: `data-memory-provenance` - **Impact**: HIGH - **Phases**: govern - **ASI**: ASI06 Every stored memory item carries its origin and trust tier; a memory written from untrusted content is quarantined and cannot influence a privileged action without human review ## Memory Scoring Formula - **Slug**: `data-memory-scoring` - **Impact**: MEDIUM - **Phases**: advisory - **ASI**: — Provides optimal memory retrieval ranking ## Forward-Only, Branch-First Migrations - **Slug**: `data-migrations-forward-only` - **Impact**: HIGH - **Phases**: advisory - **ASI**: — Keeps schema change safe and auditable by making migrations additive, ordered, and tested on a branch before main ## Orphan Data Cleanup - **Slug**: `data-orphan-cleanup` - **Impact**: MEDIUM - **Phases**: advisory - **ASI**: — Prevents data bloat from orphaned records ## TTL by Data Type - **Slug**: `data-ttl-types` - **Impact**: MEDIUM - **Phases**: advisory - **ASI**: — Ensures proper data lifecycle management and compliance ## Evaluation Loop (Test + Evaluate, Hold-out, Anchored Judge) - **Slug**: `eval-loop` - **Impact**: CRITICAL - **Phases**: govern - **ASI**: ASI08 Gives a non-deterministic system a trustworthy way to detect behavioural regressions without letting it optimise its own grader ## Deterministic Boundary of the Model - **Slug**: `frontier-deterministic-boundary` - **Impact**: CRITICAL - **Phases**: floor - **ASI**: ASI01 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 ## The Agent Charter Is Finalized as the Leave-Behind - **Slug**: `handover-agents-charter-final` - **Impact**: HIGH - **Phases**: handover - **ASI**: ASI10 AGENTS.md leaves the mission as the standing constraint on every future agent — verification commands, judgment boundaries, never/PR rules — so the next agent inherits the discipline, not just the code ## The Redone-Task Proof - **Slug**: `handover-redone-task-proof` - **Impact**: CRITICAL - **Phases**: handover - **ASI**: ASI09 A hand-over is proven by a real task redone end to end without the departing builder — recorded, dated, pointed at — so autonomy is a fact, not a farewell promise ## The Runbook Is Executable, Not Descriptive - **Slug**: `handover-runbook-executable` - **Impact**: HIGH - **Phases**: handover - **ASI**: ASI08 The recovery runbook carries real commands for the gestures that matter at 3 a.m. — start, observe, debug, resume, swap the provider, rerun the bench, process a suspended approval — so an incident meets procedures, not prose ## The Succession Is Named - **Slug**: `handover-succession-named` - **Impact**: HIGH - **Phases**: handover - **ASI**: — The system leaves the mission with a named owner, an escalation path and a review cadence — an unowned agentic system in production is an incident with a start date ## New Feature = New Adapter - **Slug**: `hexa-adapter-pattern` - **Impact**: HIGH - **Phases**: architect, floor - **ASI**: — Keeps core business logic clean and external integrations isolated ## Hexagonal Architecture Structure - **Slug**: `hexa-architecture` - **Impact**: HIGH - **Phases**: architect, floor - **ASI**: — Enables testability, maintainability, and clean dependency management ## Move the Deterministic out of the Model - **Slug**: `hexa-move-deterministic-out` - **Impact**: CRITICAL - **Phases**: floor - **ASI**: ASI01, ASI02 Reduces LLM costs and latency by moving deterministic logic out of LLM calls ## Stack Posture (Sober Default plus Trigger), Not a Fixed Stack - **Slug**: `hexa-recommended-stack` - **Impact**: MEDIUM - **Phases**: advisory - **ASI**: — Replaces a frozen product stack with a portable rule for choosing technology by evidence, so the rule does not age with any vendor ## A Thin Model Abstraction You Own (Not a Heavy Chain Framework) - **Slug**: `hexa-typescript-native` - **Impact**: HIGH - **Phases**: architect - **ASI**: — Reduces token overhead, improves debuggability, removes volatile dependencies by keeping a light abstraction you control instead of a heavy framework ## Alert Configuration - **Slug**: `observability-alert-configuration` - **Impact**: MEDIUM - **Phases**: advisory - **ASI**: — Ensures timely notification of production issues ## LLM Metrics Tracking - **Slug**: `observability-llm-metrics` - **Impact**: MEDIUM - **Phases**: advisory - **ASI**: — Enables cost monitoring, performance optimization, and anomaly detection ## Log Providers at Startup - **Slug**: `observability-startup-provider-log` - **Impact**: LOW - **Phases**: advisory - **ASI**: — Simplifies debugging by showing configuration at startup ## Structured JSON Logs - **Slug**: `observability-structured-json-logs` - **Impact**: MEDIUM - **Phases**: advisory - **ASI**: — Enables log querying, aggregation, and alerting in production ## Tiered Memory Router - **Slug**: `patterns-memory-router-tiered` - **Impact**: HIGH - **Phases**: advisory - **ASI**: ASI06 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 ## Prompt as Program (Prompt Compiler) - **Slug**: `patterns-prompt-compiler` - **Impact**: MEDIUM - **Phases**: advisory - **ASI**: — Enables versioning, testing, and optimization of prompts ## Request ID Propagation - **Slug**: `patterns-request-id-propagation` - **Impact**: MEDIUM - **Phases**: advisory - **ASI**: — Enables end-to-end request tracing across services ## ADR Discipline and Working Journal - **Slug**: `process-adr-and-journal` - **Impact**: HIGH - **Phases**: architect - **ASI**: — Makes structural decisions traceable and reversible-by-record, so the system can be picked up by anyone without re-litigating settled choices ## Model Provider as an Adapter (Detected, Never Hardcoded) - **Slug**: `provider-llm-auto-detection` - **Impact**: CRITICAL - **Phases**: floor - **ASI**: — Keeps the model behind a port so the provider can change by configuration without touching the core ## Graceful Degradation of Optional Services - **Slug**: `provider-no-crash-missing-env` - **Impact**: HIGH - **Phases**: floor - **ASI**: — Lets the app start and run wherever it is deployed, enabling features by available config rather than crashing on a missing variable ## Codebase Metrics Thresholds - **Slug**: `quality-codebase-metrics` - **Impact**: MEDIUM - **Phases**: advisory - **ASI**: — Identifies code quality issues before they become problems ## Zod Input Validation - **Slug**: `quality-zod-input-validation` - **Impact**: MEDIUM - **Phases**: advisory - **ASI**: — Prevents invalid data from entering the system and provides type safety ## Fail-Open for the Non-Critical, Fail-Closed for the Sensitive - **Slug**: `resilience-fail-open` - **Impact**: CRITICAL - **Phases**: govern - **ASI**: ASI02, ASI08 Degrades gracefully where safe and denies safely where it matters, instead of applying one failure policy everywhere ## Multi-Provider Fallback - **Slug**: `resilience-multi-provider-fallback` - **Impact**: HIGH - **Phases**: govern - **ASI**: ASI04, ASI08 Ensures LLM availability by falling back to alternative providers ## LLM Retry with Exponential Backoff - **Slug**: `resilience-retry-backoff` - **Impact**: HIGH - **Phases**: govern - **ASI**: ASI08 Handles transient LLM failures gracefully without overwhelming the API ## Retryable vs Non-Retryable Errors - **Slug**: `resilience-retryable-errors` - **Impact**: MEDIUM - **Phases**: advisory - **ASI**: — Prevents wasted retries and ensures quick failure for unrecoverable errors ## If Doubt, Upgrade the Model - **Slug**: `routing-confidence-upgrade` - **Impact**: CRITICAL - **Phases**: advisory - **ASI**: — Prevents quality degradation from incorrect model selection ## Model Cost Ratios - **Slug**: `routing-model-cost-ratios` - **Impact**: HIGH - **Phases**: advisory - **ASI**: — Essential reference for cost optimization decisions ## Smart Routing by Complexity - **Slug**: `routing-smart-complexity` - **Impact**: HIGH - **Phases**: advisory - **ASI**: — Order-of-magnitude latency cut on simple requests and a substantial cost reduction through intelligent model selection, measured on a reference system — recalibrate on your traffic ## Database Connection Pooling - **Slug**: `scaling-db-connection-pooling` - **Impact**: MEDIUM - **Phases**: advisory - **ASI**: — Prevents connection exhaustion under load ## Distributed Rate Limiting - **Slug**: `scaling-distributed-rate-limiting` - **Impact**: HIGH - **Phases**: advisory - **ASI**: ASI08, ASI10 Enables consistent rate limiting across multiple instances ## Externalize State for Scaling - **Slug**: `scaling-state-externalization` - **Impact**: CRITICAL - **Phases**: advisory - **ASI**: — Enables horizontal scaling by removing in-process state dependencies ## Unexpected Code Execution Runs Sandboxed, Never In-Process - **Slug**: `security-code-execution-sandbox` - **Impact**: CRITICAL - **Phases**: govern - **ASI**: ASI05, ASI02 Caps the blast radius of any code the agent runs (generated or tool-provided) by isolating it from the host, secrets and network ## Provenance on Every Field, So the Human Never Trusts a Guess - **Slug**: `security-human-agent-trust` - **Impact**: HIGH - **Phases**: govern - **ASI**: ASI09 Stops a model-proposed value being read as a verified fact at the approval point — the human decides on real provenance, never on fabricated confidence ## Pin Every Consumed Tool/MCP Server by Version and Hash - **Slug**: `security-mcp-server-pinning` - **Impact**: CRITICAL - **Phases**: architect, govern - **ASI**: ASI04, ASI10 A consumed tool or MCP server is pinned by version and content hash, so a supply-chain swap or rug-pull cannot silently change what the agent may call ## Untrusted Input, Prompt Injection and the Lethal Trifecta - **Slug**: `security-prompt-injection` - **Impact**: CRITICAL - **Phases**: floor, govern - **ASI**: ASI01, ASI06 Treats prompt injection as a first-rank, structural threat constrained by architecture rather than detected by heuristics ## Re-approve a Tool on Any Change to Its Signed Definition - **Slug**: `security-tool-change-reapproval` - **Impact**: HIGH - **Phases**: govern - **ASI**: ASI02, ASI04 A change to a registered tool's definition (name, schema, description, permissions) forces re-approval before the agent may call it, closing the rug-pull window ## State as an Immutable Journal (Event Sourcing, Replay, Provenance) - **Slug**: `state-event-sourcing` - **Impact**: HIGH - **Phases**: floor - **ASI**: ASI06 Makes the agent a stateless reducer over an external, replayable journal, so truth, audit and recovery are structural rather than bolted on ## Tool Registry Pattern - **Slug**: `tools-registry-pattern` - **Impact**: HIGH - **Phases**: advisory - **ASI**: ASI02, ASI03 Replaces giant switch statements with maintainable, extensible tool management ## Tool Scope and Atomicity - **Slug**: `tools-scope-atomicity` - **Impact**: HIGH - **Phases**: floor - **ASI**: ASI02 Reduces token usage and improves LLM tool selection accuracy ## Every Port Has a Named Placement - **Slug**: `topology-port-placement-mapped` - **Impact**: HIGH - **Phases**: topology - **ASI**: — Keeps the execution topology traced port by port, so a placement never drifts unseen behind the domain ## Sovereignty Graduated by Class of Data - **Slug**: `topology-sovereignty-by-data-class` - **Impact**: CRITICAL - **Phases**: topology - **ASI**: — Prevents regulated or personal data from silently landing on a placement that cannot hold its sovereignty ## Trace Export Is a Decision, Because Traces Are Data - **Slug**: `topology-trace-export-decision` - **Impact**: HIGH - **Phases**: topology - **ASI**: — Stops the most sensitive payloads leaving under the name "telemetry" without a named, reviewed decision ## A Usage Registry, Because Risk Is Classed by Deployment - **Slug**: `topology-usage-registry-present` - **Impact**: HIGH - **Phases**: topology - **ASI**: — Lets you answer, at audit time, what runs where touching what — risk attaches to a deployment, not a platform