runward 0.6.0

package/templates/mission/mission-contract.md

@@ -0,0 +1,58 @@
+# Mission Contract: [system or mission name]
+
+> **Usage.** One page, filled with the sponsor at framing; the steering contract of the mission. It states what is delivered, on what condition it is accepted, and along which roadmap. It links the success criterion to the deliverables and the milestones, and it is the shared reference from one gate to the next. Replace every `[placeholder]`; delete this notice on delivery.
+
+**Date**: [YYYY-MM-DD] · **Sponsor**: [name or role] · **Operator(s)**: [name(s)] · **Indicative horizon**: [e.g. framing in days, floor in weeks]
+
+## Principle
+
+A deliverable is judged by its **acceptance against an observable criterion**, not by its form. Every engagement therefore carries two inseparable faces: what is handed over, and the condition that says it is done. That condition — the Definition of Done — always ties back to the success criterion set at framing. This protects both sides: no fuzzy scope, no deliverable open to interpretation.
+
+## Engagements
+
+| Engagement | Deliverables | Definition of Done |
+|---|---|---|
+| **Flash framing** | Framing note: problem, target value, observable success criterion, floor vs target split, first costed increment, hard constraints | The sponsor validates the success criterion and the floor scope; what is deferred is named |
+| **Executable floor** | System wired to real traffic; the deterministic taken out of the model as testable code; baseline observability; light architecture note | The system answers on real cases and a first proof of value is measured against the success criterion |
+| **Staged iteration** | Increments delivered; structural decisions locked as ADRs; governance, security and evaluation instrumented | Every increment is measured, every added complexity traced to a trigger, every decision traceable |
+| **Handover** | Reusable assets, tutorials, handover sessions; evidence in the code; recovery documentation | The team takes over and evolves the system without the operator — demonstrated on a task redone autonomously |
+
+## Acceptance of the whole mission
+
+Beyond each engagement, the mission is done when these four conditions hold. This is the global acceptance — the one you sign.
+
+1. A system **holds in production on real traffic**, not in a demo.
+2. The success criterion set at framing is **measured and reached**, or its gap is explained.
+3. **Governance is in place**: observability, provenance, human approval, untrusted inputs constrained.
+4. The assets are **handed over and the team is autonomous** — demonstrated, not declared.
+
+## Typical roadmap and decision gates
+
+A mission follows a constant arc, punctuated by decision gates: a milestone is crossed only when the previous one has proven itself. Durations are indicative and set at framing.
+
+```
+DoR check --> Framing --> Executable floor --> Increments --> Handover
+ (launch      (days)       (weeks)             (iterative,    (autonomy)
+ conditions)                                    on evidence)
+                       gate: floor proven?   gate: increment holds?
+```
+
+A gate is crossed on **measured evidence**, never by calendar or by principle.
+
+- **After the floor**: is the first proof of value there? If not, fix the floor — do not add complexity.
+- **After each increment**: is the gain measured and held? The next increment is justified only by an objective trigger.
+- **Before handover**: is the system governed and the team ready to take over?
+
+## The contract, to fill with the sponsor
+
+| Field | To fill in |
+|---|---|
+| **Problem** | [The real need, not the dreamed one — as observed in the process] |
+| **Success criterion** | [Observable and measurable on real traffic] |
+| **Floor** | [The smallest system that proves value] |
+| **Target** | [The full architecture aimed at, by increments — named, not built] |
+| **Engagements retained** | [flash framing / executable floor / staged iteration / handover — which apply] |
+| **Milestones & gates** | [Indicative dates and the passing condition of each gate] |
+| **Deliverables & DoD** | [Taken from the engagements table, adjusted to this mission] |
+| **Hard constraints** | [Sovereignty, regulation, security, legacy — whatever bounds the solution space] |
+| **Risks owned by the sponsor** | [Missing launch conditions (DoR), if any, each named as an owned risk] |

package/templates/mission/observability-schema.md

@@ -0,0 +1,53 @@
+# Observability Schema: [system or agent name]
+
+> **Usage.** An unobserved agentic system is ungovernable and unpredictable in cost. Observability is a design property carried by the middleware chain, never an end-of-project option. Three independent levels: structured logs, lifecycle events, per-model-call metrics. One request ID propagated from entry to every tool and model call — and to sub-agents via parent/child lineage — makes every trajectory replayable and auditable. The same trace stream also feeds continuous evaluation and provenance. Auditing a past decision means rebuilding the context as it was: the schema must let you unfold a consolidated memory back to its raw facts at the exact timestamp. Cost is steered by architecture, with explicit ceilings. Replace every `[placeholder]`; delete this notice on delivery.
+
+**Version**: [vX.Y] · **Last review**: [YYYY-MM-DD]
+
+## 1. The three levels
+
+[What is emitted at each level, and where it aggregates.]
+
+| Level | What | Fields | Use |
+|---|---|---|---|
+| **Structured logs** | one line per event, typed context | [module, request ID, session, timestamp] | [aggregation, search, alerting] |
+| **Lifecycle events** | every orchestrator step and tool call, persisted | [step, tool, input, output, status] | [trajectory replay, behavioral audit] |
+| **Per-model-call metrics** | one measurement per inference | [input tokens, output tokens, cache, tier used, duration, status, attempt] | [cost and performance tracking per agent] |
+
+## 2. Propagated request ID
+
+[The single identifier that threads the whole trajectory.]
+
+- **Origin**: [generated at system entry.]
+- **Propagation**: [passed to every tool and model call.]
+- **Parent/child lineage**: [propagated to sub-agents to reconstruct a task's tree.]
+- **Carrier field**: [field name in logs, events, and metrics.]
+
+## 3. Provenance
+
+[What makes it possible to replay exactly what the model saw, even after working memory is gone.]
+
+- **Per-inference fingerprint**: [what was actually injected into context on each call.]
+- **Associated versions**: [prompt and model version behind each output, for temporal consistency.]
+- **Linkage**: [how provenance ties to lifecycle events and metrics through the same request ID.]
+
+## 4. Unfolding a consolidated memory (audit)
+
+[The condition for an audit that holds: rebuild the context of a decision, not just observe that a call happened.]
+
+- **Consolidation pointers**: [when a memory item is consolidated, deposit pointers to its raw source facts.]
+- **Unfolding procedure**: [from a compressed item, walk the pointers back to the raw facts at the exact timestamp of the decision.]
+- **Principle**: [current execution stays light; explaining a past decision stays possible after summarization.]
+
+## 5. Cost ceilings
+
+[Recurring cost as a steered quantity, not a suffered one — from day zero.]
+
+- **Aggregate counter**: [per root task.]
+- **Ceilings per time window**: [thresholds set in advance.]
+- **Behavior on overrun**: [the orchestrator stops and returns a synthesis, instead of running open-ended.]
+- **Structural cost levers**: [the model boundary (deterministic work pays no call); tier routing (fast / balanced / deep — one tier up when in doubt); caching and prompt stability (stability beats raw token trimming).]
+
+## References
+
+- [Evaluation rubric (fed by this trace stream), runbook, related ADRs.]

package/templates/mission/port-contract.md

@@ -0,0 +1,63 @@
+# Port Contract: [port name]
+
+> **Usage.** A port expresses a domain need as a contract: provide a model completion, persist state, execute an action, read a source. The adapter that implements it may be written in any language, as long as it honors the contract. This spec describes the contract, never the implementation. Two reminders: the typed schema guards the data, but the behavioral boundary is validated (see the evaluation rubric and contract tests), not guaranteed by types; and a stable contract is not a frozen one — it is governed, it carries meaning, and it composes with legacy. The "evolution rule" section is not optional. Replace every `[placeholder]`; delete this notice on delivery.
+
+## Port: [e.g. ModelPort, PersistencePort, ActionPort, SourcePort]
+
+**Contract version**: [vX.Y]
+**Port type**: [primary (drives the domain) | secondary (driven by the domain)]
+**Known adapters**: [implementations, e.g. gateway adapter, store adapter]
+
+## Business intent
+
+[What the domain asks for, in business language, no technical detail. Why the need exists. Pin the meaning of the terms used — "client", "account", "validation" do not mean the same thing everywhere; fix this bounded context's meaning to prevent hallucinated mappings.]
+
+## Signature
+
+[The operation(s) the port exposes. For each: name, role, idempotent or not, sync or async, and whether it declares that approval is required.]
+
+```
+[operation]([input]) -> [output]
+```
+
+## Input schema
+
+[Fields, types, optionality, per-field invariants. The schema is the guard: a valid payload passes, a malformed one is rejected at the boundary.]
+
+| Field | Type | Required | Constraint |
+|---|---|---|---|
+| [field] | [type] | [yes / no] | [constraint] |
+
+## Output schema
+
+[Same columns. State what is guaranteed present and what is optional.]
+
+| Field | Type | Always present | Constraint |
+|---|---|---|---|
+| [field] | [type] | [yes / no] | [constraint] |
+
+## Invariants
+
+[Properties true before and after the operation, independent of implementation. E.g.: every output references its input; a produced ID is unique; a read never mutates state. Invariants, not types, define the deep contract.]
+
+## Errors
+
+[Declared failure modes, qualified by type so the consumer knows how to react.]
+
+| Error | Type | Meaning for the consumer |
+|---|---|---|
+| [error] | [transient / validation / business / unavailable] | [retry, degraded mode, escalate, fall back] |
+
+## Evolution rule
+
+[How this contract changes without breaking its consumers.]
+
+- **Versioned**: [the contract carries a version; every evolution advances it.]
+- **Additive by default**: [add optional fields; the consumer is a tolerant reader — it ignores unknown fields and accepts missing optional ones.]
+- **Expand then contract**: [a genuinely breaking change happens in two steps: introduce the new, migrate consumers, retire the old once unused. Never in one move.]
+- **Consumer-driven verification**: [each consumer expresses its expectations as an executable contract; a producer change that would break them fails at integration, before production.]
+- **Provenance**: [record who produces, who consumes, under which version — so impact is measured before a change, not after.]
+
+## References
+
+- [Related port, adapter, ADR, contract-test suite.]

package/templates/mission/reference-stack.md

@@ -0,0 +1,70 @@
+# Reference Stack
+
+This note is a **kit of default adapters**: enough to ship a first increment fast, without reopening every arbitration from scratch. Read it for what it is — and for what it is not.
+
+> **Framing warning.** These choices are **reversible adapter decisions**, not dogma. The boundary is the domain ports and the inter-process tool protocol; behind it, an adapter's language and a store's technology are implementation details you replace without touching the business. A default holds until an objective trigger commands a change. The transverse rule is constant: start simple, isolate by contract, add complexity only on evidence.
+
+The runnable implementation of these defaults lives in the reference floor (`floor-ts/` in this repo). This note decides; the floor shows.
+
+---
+
+## Summary table
+
+| Layer | Recommended default | Evolution trigger |
+|---|---|---|
+| Core language | One typed language for orchestration and interface (e.g. TypeScript) | Never without a technical reason; polyglot goes through a sidecar or a service, never a mix inside the core. |
+| Specialized capability | Sidecar in the library's language, exposed through the tool protocol | As soon as a capability depends on a mature ecosystem in another language (browser automation, scientific computing, specialized models). |
+| Hot-path component | Stay in the core; compiled service behind a contract only on evidence | Latency or throughput proven insufficient on the hot path. |
+| Model gateway | Single port, direct SDK, three tiers (fast / balanced / deep), governance and routing centralized | Never a heavy chain framework by default; refine routing when a task's measured quality demands it. |
+| Persistence | Local first, in-memory single-instance state, immutable journal plus derived working view | Shared store as soon as a multi-instance trigger appears (load, availability, state shared across processes). |
+| Observability | Structured logs, cycle events, per-call metrics, propagated request id | Active from the first increment; it gets completed, never retrofitted. |
+| Tests & evaluation | Pyramid: unit without network, schema contract, integration through the DI container, behavioral evaluation at the top, as a continuous loop | Re-run the evaluation bench on any change touching memory, prompt or routing. |
+
+---
+
+## Layer by layer
+
+### Core language
+
+One typed language for the agentic core (orchestrator, tool registry, use cases) and the interface avoids doubling the stack. Types are shared between back and front. The model abstraction stays thin — a direct SDK, not a heavy chain framework — to keep control of prompts, events and token cost. **Trigger:** never by habit; polyglot is justified by a library or a performance constraint, and then goes through a sidecar or a service.
+
+### Specialized capability
+
+When a capability depends on a mature ecosystem elsewhere, isolate it in its own process, consumed by the core as a tool provider through the tool protocol. The cross-language boundary stays sharp and stable. **Trigger:** a mature library lives in another ecosystem and no acceptable equivalent exists in the core language.
+
+### Hot-path component
+
+Stay in the core by default. When a component on the hot path (high-throughput gateway, heavy parallel processing, tight latency) genuinely needs a compiled language, expose it as an adapter or a service behind a contract, without contaminating the rest. **Trigger:** latency or throughput proven insufficient, measured on the real path, not anticipated.
+
+### Model gateway
+
+The model is one adapter among others, behind the model port. The gateway centralizes governance and routing: a task's estimated complexity picks the fast, balanced or deep tier, and on doubt you go one tier up rather than risk a bad answer. Multi-provider fallback behind the same port covers unavailability, without rewrite.
+
+**Default real adapter, agnostic by provider profiles.** The floor ships an OpenAI-compatible adapter that works out of the box: fill in the configuration and the app runs. The adapter stays neutral — it names no provider; a provider's quirks (required headers or fields) are resolved at assembly time by a **profile keyed on the base URL**. Adding a demanding provider is one table line, not an adapter change. A **deterministic no-key fallback** keeps development and tests off the network. And a **per-run cost cap, set from day zero**, stops and synthesizes on overrun.
+
+**Trigger:** never a heavy chain framework by default. Refine routing when a task's measured quality demands it; route deterministic tasks down to cheaper tiers. Promote a new model through shadow deployment then staged rollout, never in one move.
+
+### Persistence
+
+The agent is a stateless reducer; **state lives outside, in three layers**: an immutable interaction journal (truth, audit, replay), a derived working memory (which forgets), and prompt provenance (which reconciles). Single-instance, in-memory structures are enough for rate limits, idempotency, sessions, cache and progress. **Trigger:** move to a shared store when a multi-instance signal appears (load, availability, state shared across processes). That move changes the semantics — eventual consistency, compensation instead of a single transaction, explicit causal order, idempotency under concurrency — so you pay for it knowingly, on signal, never by default.
+
+### Observability
+
+Structured logs, cycle events, per-model-call metrics, and a request id propagated everywhere, including to sub-agents through parent/child lineage. **The same trace feeds the dashboard, the continuous behavioral evaluation, and provenance.** Explicit cost caps per root task, stop-and-synthesize on overrun. **Trigger:** observability gets completed, never retrofitted; unfolding a consolidated memory back to its raw facts becomes necessary as soon as a regulated audit demands it.
+
+### Tests & evaluation
+
+**Test the deterministic, evaluate the non-deterministic.** The pyramid: unit tests on the pure domain without network (mock model adapter), schema contract tests (valid / invalid, consumer-driven), integration through the DI container with mock adapters, behavioral evaluation at the top. Evaluation is not a final gate but a continuous loop, sampled off the hot path. Hybrid scoring: deterministic for whatever admits a guarantee, a grounded judge model only for the irreducibly behavioral, on a non-gameable hold-out. **Trigger:** re-run the bench on any change touching memory, prompt or routing; widen any self-tuning envelope only on real improvement, and never past the deterministic floor (safety, security, authorization, audit).
+
+---
+
+## What the stack does not decide
+
+- It does not decide the **problem** or the **floor** — framing does (`frame` workflow), upstream.
+- It does not make a **structural decision** without the ADR lock (`decision-loop` workflow): options, preference order, re-evaluation trigger.
+- It fixes no **behavioral boundary**: the port covers the typed contract; behavior is validated separately, by evaluation.
+
+## References
+
+- Implementation: the reference floor, `floor-ts/`.
+- Related templates: `port-contract.md`, `runbook.md`, `observability-schema.md`, `evaluation-rubric.md` (this directory).

package/templates/mission/runbook.md

@@ -0,0 +1,70 @@
+# Runbook: [system or agent name]
+
+> **Usage.** This runbook is the transfer object: it lets a team that did not build the system start it, keep it running, and bring it back after an incident. Two principles behind it. Resilience is designed in by default, not after the incident: fail-open for the non-critical, fail-closed and explicit for the sensitive action. And the agent is a reducer with no hidden state — state lives outside: recovery rereads recorded outputs and restarts from a checkpoint; it never re-calls the non-deterministic model. Filling in contacts and the provider-failover procedure is not clerical work: it is what turns an incident into a non-event. Replace every `[placeholder]`; delete this notice on delivery.
+
+**Version**: [vX.Y] · **Last review**: [YYYY-MM-DD] · **Owner**: [name or role]
+
+## 1. Startup
+
+[The boot sequence, from the strict minimum to full mode.]
+
+- **Prerequisites**: [environment, permissions, access, secrets expected in typed configuration.]
+- **Start command**: [ordered steps.]
+- **Feature detection at boot**: [the system detects which services are actually available; a missing dependency cleanly disables its feature instead of crashing.]
+- **Health check**: [how to confirm the system is up. Signals to watch: model health, persistence health, sidecar health.]
+
+## 2. Dependencies and degraded modes
+
+[For each dependency: its role, its behavior on failure, the associated degraded mode.]
+
+| Dependency | Role | Criticality | Behavior on failure |
+|---|---|---|---|
+| [model gateway] | [generation] | [critical] | [failover to fallback provider, same port] |
+| [persistence] | [state, log] | [critical] | [fail-closed on sensitive writes] |
+| [capability sidecar] | [specialized capability] | [non-critical] | [circuit breaker, feature disabled and signaled] |
+| [observability] | [traces, metrics] | [non-critical] | [silent degraded mode] |
+
+**Transverse rule**: degrade reading, never acting. A sensitive action fails closed, explicit and traced, rather than executing in doubt.
+
+## 3. Checkpoints and recovery
+
+[How state is held, and how to restart after a stop.]
+
+- **State model**: [immutable interaction log (truth, audit); derived working memory (which forgets); prompt provenance (which reconciles).]
+- **Recovery**: [restart from a checkpoint without replaying everything; reread recorded outputs; do not re-call the model.]
+- **Replication**: [if multi-instance, externalized state lives in the shared store; another instance picks up the same explicit state.]
+- **Agent suspended awaiting approval**: [state serialized durably, resources freed, agent rehydrated when the decision arrives — exactly where it stopped.]
+
+## 4. Common incidents
+
+[Expected failures, qualified by error type, with the reaction.]
+
+| Symptom | Error type | Diagnosis | Action |
+|---|---|---|---|
+| [timeout, overload] | [transient] | [check the dependency] | [retry with bounded exponential backoff] |
+| [non-conforming output] | [validation] | [read the diagnostic] | [single retry, diagnostic fed back] |
+| [missing resource] | [business] | [trace the trajectory via request ID] | [diagnose or escalate to a human] |
+| [model provider silent] | [unavailable] | [provider health] | [failover — see section 6] |
+| [cost overrun] | [ceiling] | [aggregate counter per root task] | [stop, synthesis returned] |
+
+## 5. Contacts
+
+| Role | Person | Channel | Scope |
+|---|---|---|---|
+| [technical on-call] | [name] | [channel] | [operations] |
+| [product owner] | [name] | [channel] | [business decisions] |
+| [sensitive-action approver] | [name] | [channel] | [human validation] |
+| [model infrastructure provider] | [contact] | [channel] | [escalation] |
+
+## 6. Model provider failover
+
+[Keep availability failover sharply distinct from promoting a new model.]
+
+- **Availability failover (immediate)**: [primary provider drops; automatic switch to the fallback behind the same port, no rewrite. Verify the fallback is healthy; watch for divergence.]
+- **Manual override**: [how to force the switch when the automation does not trigger.]
+- **Promoting a new model (earned)**: [never in one move. Validate in shadow deployment on real traffic; measure behavioral divergence with the same evaluation; roll out in stages with instant rollback on any regression.]
+- **Rollback**: [how to return to the previous provider, and on which signal.]
+
+## References
+
+- [Observability schema, threat model, evaluation rubric, related ADRs.]

package/templates/mission/shared-bricks.md

@@ -0,0 +1,74 @@
+# Shared Bricks
+
+> **Usage.** Read this note when a capability the mission needs already exists — or should exist — beyond the application: a model gateway, a connector bank, a skill catalog, shared memory, a registry. It gives the placement families, the stable criteria, and a matrix of the common bricks, each with a sober default and its trigger. It decides *where a brick lives*; the port that consumes it is decided in `architecture.md`, and every placement switch is an ADR.
+
+## The move that does not change the rule
+
+A brick leaving the application changes nothing for the domain. The application consumed it through a port before; it consumes it through the same port after. The only question is what stands behind the port — in-process code, a service the platform team runs, a managed product. That placement is a **reversible adapter decision**, arbitrated like every line of the decision matrix: one sober default, one explicit trigger, and an ADR when the trigger fires. If moving a brick would force the domain to change, the boundary was wrong — fix the port before moving anything.
+
+## The recursive pattern: contract, index, implementation
+
+Every shared brick decomposes into three things that never merge:
+
+- the **contract** — versioned, additive, tolerant reader — that consumers code against;
+- the **index** that publishes and resolves what exists (which connectors, which skills, which models): it publishes and it resolves, it does not orchestrate. **The index is an index, not a brain.**
+- the **implementation** behind the contract, replaceable without touching a single consumer.
+
+This is the same discipline that keeps the tool registry thin inside the application, replayed at platform scale: **delivery delivers, the orchestrator decides.** A brick that starts deciding for its consumers has stopped being a brick and become a dependency you cannot leave.
+
+## Five placement families
+
+| Family | What stands behind the port |
+|---|---|
+| **In-app** | A module of the application itself — the starting point for everything |
+| **Existing infrastructure** | Infrastructure the organization already operates: API gateway, message bus, identity provider |
+| **Dedicated internal platform** | A product run by a platform team, serving many applications |
+| **Managed infrastructure service** | A cloud provider's neutral runtime: queues, workflow engines, observability stacks |
+| **Managed model-vendor runtime** | The model vendor's own platform hosting agents, tools or memory |
+
+Each family further from the top trades control for leverage. None is right in general; each is right under criteria.
+
+## Six stable criteria
+
+The families change with the market; the criteria do not. Weigh every placement against:
+
+1. **Sovereignty & control** — who can read the data, change the behavior, revoke the access.
+2. **Reuse** — how many consumers actually benefit from sharing this brick.
+3. **Velocity** — what the placement does to the team's iteration speed, now and at handover.
+4. **Cost & dependency** — the bill, and the cost of leaving.
+5. **Reuse of existing** — what the organization already runs, staffs and knows how to audit outranks a new component of equal merit.
+6. **Compliance** — certifications, data residency, auditability the deployment must inherit.
+
+## The brick matrix
+
+One sober default and one trigger per brick — the decision-matrix discipline applied beyond the application.
+
+| Brick | Sober default | Trigger to move |
+|---|---|---|
+| **Model gateway** | One model port in-app, direct SDK | A second application needs the same routing, quotas and audit — shared gateway on existing infra or an internal platform |
+| **Connector bank** | Connectors as in-app adapters | The same connector is being rewritten for a third consumer — publish it behind a contract, listed in an index |
+| **Skill catalog** | Skills versioned in the app repository | Skills are shared across teams — a catalog with curation, provenance and versioning |
+| **Shared memory** | Per-app memory: journal plus derived view | A second application needs the same facts — a memory service with access control per data class |
+| **Discovery registry** | A static list in configuration | Entries change faster than releases, or third parties publish into it — a registry that publishes and resolves, still not a brain |
+| **Durable execution** | In-app suspend-and-rehydrate on the journal | Several apps rebuild the same suspend/resume machinery — a workflow engine, managed or internal; it carries the control flow and the durability, never the reasoning or the business, and the model call stays a recorded activity you re-read, never replay |
+| **Delivery & evaluation** | CI plus the eval harness per app | Rubrics and shadow deployments duplicated across teams — shared evaluation infrastructure; delivery delivers, the orchestrator decides |
+| **Observability** | Structured logs and metrics per app, common schema | Cross-app trajectories must be reconstructed — a shared trace store, placed under the sovereignty rule below |
+| **Identity & secrets** | The existing IdP and vault | Agents need their own principals at scale — an agent-identity extension of the existing IdP, never a parallel identity system |
+
+**Reconciliation with the doctrine's defaults.** Where doctrine §15 leans on *existing infrastructure* as the sober default for the model gateway, the connector bank and observability — under criterion 5, what the organization already runs, staffs and audits outranks a new component of equal merit — this template defaults those three to **in-app, per-app** instead. The divergence is deliberate and narrow: the doctrine bricks assume an enterprise whose infrastructure is already operated, while a runward mission starts on a greenfield floor where no such infra exists to reuse yet. In-app is the honest starting point here, not a rejection of the criterion. The moment a second consumer appears — or an already-operated brick is on hand — criterion 5 reasserts itself and each brick's own trigger moves placement onto existing infrastructure. Same rule, different starting inventory.
+
+## Sovereignty, graduated by data class
+
+Sovereignty is not one rule per brick; it is one rule per **class of data** crossing the brick. Public reference data can live on a managed vendor runtime; internal business data raises the bar; regulated or personal data pushes placement toward the internal families — and the class is decided at field level, not system level. Two facts are constantly underestimated: **traces are data** — an observability pipeline that ships prompts and tool arguments to a third party is exporting your most sensitive payloads under the name "telemetry"; and **third-party export is exfiltration** unless a decision says otherwise — same review as any data transfer: named recipient, named data class, named retention.
+
+## The usage registry
+
+Keep a registry of who deploys what on which brick, because risk is classed **by deployment, not by platform**. The same internal platform hosts a harmless FAQ bot and an agent with write access to payments; a platform-level risk label would either strangle the first or wave the second through. Governance attaches to each deployment — its data classes, its action scopes, its approval points — and the registry is what lets you answer, at audit time, "what runs where, touching what."
+
+## The lesson of the layers
+
+Every layer commoditizes. Yesterday's hand-rolled orchestration is today's managed workflow engine; today's bespoke gateway is tomorrow's product. The lesson is not to guess the winner — it is to **consume every brick through a contract and never weld the domain to a brick's SDK**. When the layer commoditizes, you swap the implementation and keep the contract; the applications above it do not notice.
+
+## A third party is untrusted input
+
+The moment a brick admits third-party content — connectors, skills, registry entries, remote tools — **curation is not optional**: review before listing, provenance recorded, capability scopes declared, and the 2-of-3 rule applied to whatever the content can reach (see `governance/threat-model.md`). An index that lists anything unreviewed is not a registry; it is an attack surface with a search box.

package/templates/mission/threat-model.md

@@ -0,0 +1,53 @@
+# Threat Model: [system or agent name]
+
+> **Usage.** This threat model maps the attack surfaces specific to an agentic system and fixes the guardrails. Principle: you do not defend against injection with detection — unreliable, especially for indirect injection — but with architecture. The model is not a trust boundary. The first-rank threat is prompt injection, intrinsic to any memory or retrieval. The worst case arises when a **lethal trifecta** — private-data access, untrusted-content ingestion, outbound communication — meets on one unguarded path; removing any one of the three defuses it. Operational rule: allow at most **two of the three while untrusted content is in the context window**; when all three are needed, the action goes under human supervision, never autonomous. Replace every `[placeholder]`; delete this notice on delivery.
+
+**Version**: [vX.Y] · **Last review**: [YYYY-MM-DD] · **Agent privilege level**: [low | high]
+
+## 1. Attack surfaces
+
+[List every way a hostile instruction or datum can enter or act.]
+
+| Surface | Description | Trust | Primary risk |
+|---|---|---|---|
+| **Untrusted input (direct)** | [user input] | untrusted | [direct injection] |
+| **Untrusted input (indirect)** | [retrieved content: page, document, memory item] | untrusted | [indirect injection, fired at ingestion] |
+| **Memory** | [working memory, consolidated items] | untrusted by inheritance | [persisted injection, replayed later] |
+| **Tools** | [tool registry exposed to the model] | guarded | [unauthorized call of an impactful tool] |
+| **Exposed surface** | [tool server published by the system] | guarded | [unauthenticated access, unbounded rate] |
+| **Secrets and sensitive data** | [configuration, private data] | internal | [exfiltration] |
+
+## 2. Lethal trifecta
+
+[Assess the three properties on every sensitive path. The danger is never one property alone; it is their meeting.]
+
+| Path / context window | Private data | Untrusted content ingested | Outbound communication | Verdict |
+|---|---|---|---|---|
+| [path] | [yes / no] | [yes / no] | [yes / no] | [safe (2 of 3) / human supervision (3 of 3)] |
+
+**Context-window rule**: at most two of the three properties at once **while untrusted content is present in the context window** (the scope is the context, not the session — a session may hold many contexts, and the risk exists exactly as long as the untrusted content does). If all three are genuinely required on one path, the action does not run autonomously — it goes under human validation. For every three-of-three path, document which property is removed, or why supervision is imposed instead.
+
+## 3. Guardrails
+
+[The non-negotiable base as soon as external content is ingested.]
+
+- **Separation of the untrusted**: [retrieved content treated as data, never as instruction; kept apart from instructions; purged from context after use.]
+- **Least privilege on tools**: [the model sees only what it may call; the registry is filtered by role before the model sees it.]
+- **Human approval**: [on consequential actions and any outbound communication.]
+- **Output validation**: [tool and model outputs validated by schema before they act.]
+- **Immutable log**: [any injected action stays traceable and reversible.]
+- **High-privilege patterns (if applicable)**: [proportionate to risk: pre-approved action sets (action selector); plan frozen before exposure to tool outputs (plan-then-execute); isolation of untrusted processing; or a privileged planner split from a quarantined model that only reads the untrusted (dual model).]
+
+## 4. Approval points
+
+[Actions that require human approval — declared in the tool's contract, enforced by infrastructure.]
+
+| Action | Approval trigger | Presentation to the human | If no response |
+|---|---|---|---|
+| [mutation, write, external push] | [always / above threshold] | [deterministic summary, faithful to the tool's real arguments — never a model paraphrase] | [agent suspended in durable state, resources freed, rehydrated on decision] |
+
+**Reminder**: the approval summary is itself an attack surface. It must be deterministic and faithful to the real arguments, or an injected action slips through in the batch. Group low-urgency requests into a prioritized queue with summaries, so approvers are not trained to rubber-stamp.
+
+## References
+
+- [Related hardening ADR, observability schema, evaluation rubric.]

package/templates/rules/async-job-guardrails.md

@@ -0,0 +1,95 @@
+---
+title: Background Job Guardrails (Retry, Idempotency, Bounded Concurrency, Job Observability)
+impact: HIGH
+impactDescription: 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
+tags: [async, jobs, idempotency, concurrency, retry, observability]
+---
+
+## Background Job Guardrails
+
+> **A background job without guardrails is an incident on a delay.**
+
+Post-turn pipelines and maintenance crons run off the hot path, where nobody is watching. That is exactly why they need harder guardrails than the interactive turn, not softer ones. Four are non-negotiable — all four, on every job:
+
+1. **Bounded retry, per step.** Each step retries independently, with backoff and a hard cap. Exhausted jobs park in a dead-letter state for inspection; nothing retries forever.
+2. **Idempotency.** Every real queue delivers at-least-once, so duplicates are a certainty, not an edge case. Each job carries an idempotency key derived from its cause (`extract-facts:turn-123`), and execution begins with an **atomic claim** — a unique-constraint insert, never check-then-insert — so concurrent deliveries collapse to one execution.
+3. **Bounded concurrency.** A global cap protects downstream systems (the database, the model provider); a per-user partition keeps one heavy tenant from starving everyone else.
+4. **Job observability.** Queue lag and failure rate are first-class metrics with alerts, at the same severity as user-facing latency. A queue that grows silently for three days is an outage you learn about from the user.
+
+**Incorrect:**
+
+```typescript
+// No guardrails: each absence is a distinct production incident.
+queue.on('job', async (job) => {
+  while (true) {                       // BAD: unbounded retry storm
+    try {
+      await handlers[job.type](job);   // BAD: no idempotency key —
+      break;                           //      redelivery = double-processing
+    } catch { /* retry immediately */ }
+  }
+});
+
+await Promise.all(pending.map(run));   // BAD: unbounded fan-out melts the DB
+// BAD: and no metrics — the queue can rot for days unseen
+```
+
+**Correct:**
+
+```typescript
+async function runJob(job: Job): Promise<void> {
+  // 1. Idempotency: atomic claim — a concurrent duplicate loses the
+  //    insert itself, not a racy check that both callers pass.
+  const claimed = await db.tryInsert('job_executions', {
+    key: job.idempotencyKey,          // e.g. 'extract-facts:turn-123'
+    claimedAt: new Date(),
+  });
+  if (!claimed) {
+    metrics.increment('jobs.deduplicated', { type: job.type });
+    return;
+  }
+
+  // 2. Bounded concurrency: global cap plus per-user partition.
+  const slot = await semaphore.acquire({
+    global: 32,
+    partition: { key: job.userId, limit: 2 },
+  });
+
+  const startedAt = Date.now();
+  try {
+    // 3. Bounded retry with backoff; then dead-letter, never forever.
+    await withRetry(() => handlers[job.type](job), {
+      maxRetries: 3,
+      backoff: 'exponential',
+    });
+    metrics.histogram('jobs.duration_ms', Date.now() - startedAt, { type: job.type });
+  } catch (error) {
+    await deadLetter.park(job, error);   // inspectable, replayable
+    metrics.increment('jobs.failed', { type: job.type });
+  } finally {
+    slot.release();
+  }
+}
+
+// 4. Job observability: lag and failure rate are first-class signals.
+setInterval(async () => {
+  metrics.gauge('jobs.queue_lag_seconds', await queue.oldestPendingAgeSeconds());
+  metrics.gauge('jobs.failure_rate_15m', await queue.failureRate({ window: '15m' }));
+}, 30_000);
+// Alert: queue_lag > 300s or failure_rate > 5% —
+// same severity as user-facing latency.
+```
+
+**Why this matters:**
+
+- **At-least-once is the contract** of every production queue. Without the atomic idempotency claim, the same fact gets extracted twice, the same reminder fires twice, the same erasure runs half twice — and under concurrency, a check-then-insert passes for both callers.
+- **Unbounded retry is a self-inflicted outage**: a failing provider gets hammered by its own victims, and the queue amplifies the incident instead of absorbing it.
+- **Unbounded fan-out** turns a backlog into a database or provider meltdown, and one bulk-importing tenant into everyone's problem.
+- **Invisible background failure degrades the system in a way nobody can date**: memory quietly stops updating, summaries go stale, and by the time answers feel wrong the cause is weeks old. Queue lag and failure rate make the rot visible the hour it starts.
+
+**Checklist:**
+
+- [ ] Every step has bounded retry with backoff; exhausted jobs park in a dead-letter state, never loop forever.
+- [ ] Every job carries an idempotency key derived from its cause; the claim is atomic and holds under concurrent delivery.
+- [ ] Concurrency is capped globally and partitioned per user or tenant.
+- [ ] Queue lag and failure rate are emitted and alerted on, at the same severity as user-facing metrics.
+- [ ] Dead-lettered jobs are inspectable and replayable after the cause is fixed.