runward 0.6.0

package/templates/rules/tools-registry-pattern.md

@@ -0,0 +1,153 @@
+---
+title: Tool Registry Pattern
+impact: HIGH
+impactDescription: Replaces giant switch statements with maintainable, extensible tool management
+tags: [tools, architecture, patterns, maintainability]
+---
+
+## Tool Registry Pattern
+
+Replace switch statements with a registry pattern for tool execution. Easier to test, extend, and maintain.
+
+**Incorrect:**
+
+```typescript
+// BAD: Giant switch statement
+async function executeTool(name: string, input: unknown): Promise<ToolResult> {
+  switch (name) {
+    case 'get_project':
+      return await getProject(input as GetProjectInput);
+    case 'analyze_market':
+      return await analyzeMarket(input as AnalyzeMarketInput);
+    case 'search_documents':
+      return await searchDocuments(input as SearchDocumentsInput);
+    // ... 50 more cases
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+```
+
+**Correct:**
+
+```typescript
+// Tool interface
+interface ITool {
+  name: string;
+  description: string;
+  schema: z.ZodSchema;
+  execute(input: unknown, ctx: ToolContext): Promise<ToolResult>;
+}
+
+// Tool context for shared dependencies
+interface ToolContext {
+  userId: string;
+  tenantId: string;
+  db: Database;
+  logger: Logger;
+}
+
+// Registry class
+class ToolRegistry {
+  private tools = new Map<string, ITool>();
+
+  register(tool: ITool): void {
+    if (this.tools.has(tool.name)) {
+      throw new Error(`Tool already registered: ${tool.name}`);
+    }
+    this.tools.set(tool.name, tool);
+  }
+
+  get(name: string): ITool | undefined {
+    return this.tools.get(name);
+  }
+
+  async execute(name: string, input: unknown, ctx: ToolContext): Promise<ToolResult> {
+    const tool = this.tools.get(name);
+    if (!tool) {
+      throw new ToolNotFoundError(name);
+    }
+
+    // Validate input with Zod
+    const validated = tool.schema.parse(input);
+
+    // Execute with context
+    return tool.execute(validated, ctx);
+  }
+
+  // For LLM: get all tool definitions
+  getDefinitions(): ToolDefinition[] {
+    return Array.from(this.tools.values()).map(t => ({
+      name: t.name,
+      description: t.description,
+      parameters: zodToJsonSchema(t.schema),
+    }));
+  }
+}
+
+// Example tool implementation
+const getProjectTool: ITool = {
+  name: 'get_project',
+  description: 'Retrieves project details by ID',
+  schema: z.object({
+    projectId: z.string().uuid(),
+  }),
+  async execute(input, ctx) {
+    const project = await ctx.db.projects.findUnique({
+      where: { id: input.projectId, tenantId: ctx.tenantId },
+    });
+    return { success: true, data: project };
+  },
+};
+
+// Registry setup
+const registry = new ToolRegistry();
+registry.register(getProjectTool);
+registry.register(analyzeMarketTool);
+registry.register(searchDocumentsTool);
+
+// Usage
+const result = await registry.execute('get_project', { projectId: '...' }, ctx);
+```
+
+**Benefits:**
+
+- Each tool is independently testable
+- Easy to add new tools (just register)
+- Automatic schema validation
+- Centralized logging and metrics
+- No giant switch to maintain
+
+**Advanced: Tool middleware:**
+
+```typescript
+class ToolRegistry {
+  private middleware: ToolMiddleware[] = [];
+
+  use(middleware: ToolMiddleware): void {
+    this.middleware.push(middleware);
+  }
+
+  async execute(name: string, input: unknown, ctx: ToolContext): Promise<ToolResult> {
+    // Apply middleware chain
+    let handler = (input: unknown) => this.executeCore(name, input, ctx);
+
+    for (const mw of this.middleware.reverse()) {
+      const next = handler;
+      handler = (input) => mw(name, input, ctx, next);
+    }
+
+    return handler(input);
+  }
+}
+
+// Logging middleware
+const loggingMiddleware: ToolMiddleware = async (name, input, ctx, next) => {
+  const start = Date.now();
+  const result = await next(input);
+  ctx.logger.info('Tool executed', { name, duration: Date.now() - start });
+  return result;
+};
+
+registry.use(loggingMiddleware);
+```

package/templates/rules/tools-scope-atomicity.md

@@ -0,0 +1,103 @@
+---
+title: Tool Scope and Atomicity
+impact: HIGH
+impactDescription: Reduces token usage and improves LLM tool selection accuracy
+tags: [tools, llm, architecture, cost-optimization]
+---
+
+## Tool Scope and Atomicity
+
+Each tool should do ONE atomic action. Avoid catch-all tools that confuse the LLM.
+
+**The Problem:**
+
+Tools that do everything:
+- Use more tokens in descriptions
+- Confuse the LLM about when to use them
+- Make debugging harder
+- Can't be cached or optimized individually
+
+**Incorrect:**
+
+```typescript
+// BAD: Catch-all tool
+const analyzeProjectTool = {
+  name: 'analyze_project',
+  description: 'Analyzes project overview, market fit, traction, team, financials, and generates recommendations',
+  parameters: {
+    projectId: { type: 'string' },
+    analysisType: { type: 'string', enum: ['overview', 'market', 'traction', 'team', 'finance', 'all'] },
+  },
+};
+
+// BAD: Vague tool
+const getInsightsTool = {
+  name: 'get_insights',
+  description: 'Gets insights about anything',  // Too vague
+};
+```
+
+**Correct:**
+
+```typescript
+// GOOD: Atomic tools - one action each
+const tools = [
+  {
+    name: 'get_project_overview',
+    description: 'Retrieves basic project information: name, stage, sector, founding date. Use for initial context.',
+    parameters: { projectId: { type: 'string', required: true } },
+  },
+  {
+    name: 'analyze_market_fit',
+    description: 'Evaluates product-market fit based on user feedback and metrics. Use when assessing market validation.',
+    parameters: { projectId: { type: 'string', required: true } },
+  },
+  {
+    name: 'assess_traction',
+    description: 'Calculates traction metrics: MRR growth, user growth, engagement. Use for performance assessment.',
+    parameters: { projectId: { type: 'string', required: true } },
+  },
+  {
+    name: 'get_team_assessment',
+    description: 'Returns team composition and experience analysis. Use when evaluating team strength.',
+    parameters: { projectId: { type: 'string', required: true } },
+  },
+];
+```
+
+**Principles:**
+
+1. **One tool = One action** - Atomic operations
+2. **2-3 examples max** - Don't bloat descriptions
+3. **Explicit "when to use"** - Guide LLM selection
+4. **Group by domain** - Organize related tools together
+
+**Tool Documentation Template:**
+
+```typescript
+interface ToolDefinition {
+  name: string;           // verb_noun format: get_project, analyze_market
+  description: string;    // What it does + when to use it
+  parameters: {
+    // Only required parameters, minimal
+  };
+}
+
+// Example
+{
+  name: 'search_documents',
+  description: 'Searches project documents by keyword. Use when user asks about specific topics or needs to find information in uploaded files.',
+  parameters: {
+    projectId: { type: 'string', required: true },
+    query: { type: 'string', required: true },
+    limit: { type: 'number', default: 10 },
+  },
+}
+```
+
+**Signs of tool bloat:**
+
+- Tool description > 100 words
+- More than 5 parameters
+- "or" in the description (does multiple things)
+- Enum with > 5 options

package/templates/targets/AGENTS.md

@@ -0,0 +1,32 @@
+# Agent charter — Runward mission
+
+This project is delivered with the Runward method: floor first, evolution on evidence, governance from day zero. Any agent working here follows this charter. It is vendor-neutral: the method lives in `runward/workflows/`, the mission state in `runward/`.
+
+## Non-negotiable boundaries
+
+1. **The architecture constrains the model, not the other way around.** The model is a replaceable adapter behind a stable port. No domain logic in prompts, no prompt fragments in the domain. This principle is the opening posture, not the whole frame: the five architecture gestures the workflows apply (named in `runward/workflows/method.md`) and the decision matrix (`runward/decision-matrix.md`) carry the complete method.
+2. **Boundaries before the stack.** Ports and contracts are decided before languages, frameworks or topology. Contracts are versioned, additive, tolerant-reader. One single language in the core; polyglot only as a sidecar behind the tool protocol, on a proven trigger.
+3. **Complexity is deferred until a trigger commands it.** Multi-agent, long-term memory, service extraction, a bigger model: each requires an objective trigger recorded in an ADR. No trigger, no change.
+4. **Deterministic frontier.** Anything that can be computed deterministically is. The model never invents figures that the system can compute.
+5. **Security on actions, not display.** Untrusted input never gains write or exfiltration capability in the same session (lethal trifecta, 2-of-3 rule). Reads may fail open; actions fail closed.
+
+## How to work
+
+- Apply the craft rules in `runward/rules/` while building: they cover memory scoring, tiered retrieval, event sourcing, request-id propagation, resilience, cost routing, secrets and prompt-injection defenses. When a rule and a habit conflict, the rule wins; deviating from a rule requires an ADR.
+- Consult `runward/decision-matrix.md` before adding any capability: 22 arbitrations, each with a sober default and an explicit trigger. No trigger, no change.
+- Before any structural decision, run `runward/workflows/decision-loop.md`: verify in the real code, check the sourced state of the art, challenge the source, take a durable position, lock it in an ADR — only then edit.
+- One ADR per structural decision, in `runward/adr/`, with a dated re-evaluation trigger. Use the template `runward/adr/ADR-0000-template.md`.
+- Current phase and gates: see `runward/framing.md` (Definition of Ready) and each workflow's Definition of Done. Do not skip a gate on assertion; pass it on evidence.
+- Show before you build: for any deliverable meant for humans, produce a reviewable preview first.
+- Never mark a phase done if its Definition of Done is not demonstrably met.
+
+## Mission state
+
+| File | What it holds |
+|---|---|
+| `runward/framing.md` | Problem, value, observable success criterion, floor vs target |
+| `runward/architecture.md` | Boundaries, ports, integration protocol |
+| `runward/floor.md` | The floor's scope and its measured proof |
+| `runward/adr/` | Decision journal |
+| `runward/governance/` | Threat model, evaluation rubric, observability schema |
+| `runward/runbook.md` | Recovery runbook for the receiving team |

package/templates/workflows/architect.md

@@ -0,0 +1,50 @@
+# Architect — Boundaries Before Stack
+
+## When to use
+
+Use this workflow once framing is decided and structure must follow: "how do we architect this?", "what do we build on?", "which contracts?", "monolith or microservices?", "which backend language?" (answer: ports first). This is phase 2 of `method`. It turns a decided perimeter into a decided architecture: boundaries fixed, contracts named, language and topology deliberately left open.
+
+## Inputs
+
+- The framing note: floor/target split, success criterion, hard constraints, presumed boundaries.
+- The `mission/architecture.md`, `mission/port-contract.md`, and `mission/adr/ADR-0000-template.md` templates.
+
+## Outputs
+
+- A light architecture note.
+- The port list with contracts and the integration protocol.
+- One ADR per structuring decision.
+
+## Procedure
+
+**Refuse stack questions, again.** Contracts first, technology later. The phase rests on the method's founding inversion — the LLM Boundary Principle: the architecture constrains the model, never the reverse. The model and the infrastructure are adapter decisions, taken behind stable contracts. That is why boundaries come before stack. Each stack choice is taken adapter by adapter once boundaries are known, justified by a local technical reason — never by habit.
+
+**Fix the two boundaries that make the stack secondary.**
+
+1. **Domain ports.** The domain expresses its needs as contracts: generate a model completion, persist state, execute an action, read a source. Each contract is honored by an adapter written in any language, as long as it honors the contract. The model port is a port like any other: the reasoning engine is bound only by its contract, not by its brand. The daily dividend is a domain testable without the model; substitutability is the insurance you keep in reserve. This is the founding inversion made concrete: the model is a replaceable adapter behind a stable port.
+2. **The cross-process integration protocol.** When a capability lives in another process or language, expose it through a standardized tool protocol. The system consumes that process as a tool provider and publishes its own capabilities the same way. A service is just an adapter that moved into its own process; the domain does not change.
+
+**Govern every contract.** A port is more than a typed schema. Version it; make changes additive by default; read as a tolerant reader that ignores unknown fields and accepts missing optional ones. For a genuinely breaking change, expand then contract: introduce the new, migrate consumers, retire the old — never in one move. Track provenance: who produces, who consumes, under which version, so impact is measurable before a change. Fix meaning per bounded context: without pinned semantics the model will invent false mappings; the semantic contract is to meaning what the typed schema is to malformed data. On legacy, the adapter becomes an anticorruption layer that translates the old dialect into the domain language without contaminating the new — and that boundary is never free: name the translation cost and budget it.
+
+**Name the default topology and its triggers.** A modular hexagonal monolith by default: one deployable, pure domain plus adapters. A single orchestrator directing specialists: it composes, it carries no business logic. A tool registry plus a middleware chain as the single transversal surface (logging, access, cost, approval, traces) — the chain stays thin, the registry stays an index, never a brain. One core language for server and interface, a thin model abstraction (a direct SDK, not a heavy chain framework); polyglot only via a sidecar or service, justified by a mature library or proven performance need. Name each default's evolution trigger here; cross it only in `iterate`.
+
+**Lock structuring choices in ADRs.** Starting topology, core language, legacy integration strategy, bounded-context boundaries: each goes through `decision-loop` — reality-check against reference implementations, sourced state of the art, challenge, durable position, written lock. A decision that is not locked does not enter the architecture note.
+
+**Write the architecture note.** Short, readable, decided: the ports, the default topology and its triggers, what stays open (language, provider), and the target named without being built. A few pages, not a detailed design dossier.
+
+## Definition of Done
+
+- Architecture note produced, boundaries first, stack open.
+- Every port named with contract and initial version; integration protocol stated.
+- One ADR per structuring choice, locked before the note mentions it.
+- Note reviewed via `review` before circulation.
+- Deliverable form matched: the presented architecture note carries an expected delivery form (a readable PDF or HTML); ADRs and contract specs stay as repository markdown.
+
+## Anti-patterns
+
+- Deciding language, framework, or provider at this phase.
+- Building microservices or multi-agent into the starting topology instead of naming them in the target.
+- Confusing typed contracts with behavior: the behavioral boundary is validated in `govern`, never guaranteed by types.
+- Writing the note before the ADRs are locked.
+- Pretending the boundary is free on legacy — the integration cost concentrates exactly there.
+- Letting the middleware chain accumulate orchestration or business logic.

package/templates/workflows/brownfield.md

@@ -0,0 +1,52 @@
+# Brownfield — Enter a Mission That Already Has a Past
+
+## When to use
+
+Use this workflow whenever the mission does not start on green grass: "resume the mission in progress", "we inherited a half-built project", "this system ignores our principles, audit it", "rebuild a clean one from the old one", "where were we?". The default chain in `method` starts from framing on greenfield; most real missions start elsewhere. Establish the entry point with the sponsor, reconstruct what is missing, then re-enter the chain at the right phase — never by instinct.
+
+## Inputs
+
+- Access to the existing system: code, deployments, data, and whatever artifacts exist.
+- The sponsor's intent: resume, join, rebuild, or derive.
+- The framework's templates for retrofitted artifacts (`mission/framing.md`, `mission/architecture.md`, `mission/adr/`).
+
+## Outputs
+
+- The entry mode identified and agreed.
+- The missing upstream artifacts reconstructed.
+- Re-entry into the `method` chain at the correct phase.
+
+## Procedure
+
+**Enforce the entry rule.** Characterize before you touch; never rewrite in one block. On an existing system the first move is not to propose a target — it is to understand what is there, what works, and why it is the way it is. Value is reconquered tier by tier, exactly as on greenfield; a mass rewrite destroys the value already in place and postpones all proof.
+
+**Identify the entry mode.** Four modes; when they overlap, calibrate on the most demanding one.
+
+- **M1 — Resume your own mission.** Artifacts exist: framing note, ADRs, journal, code. Opening move: reread them, rebuild the state, locate the phase reached, spot what has aged, and pick the chain back up where it stopped. The state of a mission is its persisted artifacts, never anyone's memory.
+- **M2 — Join a project in flight.** The project exists, usually without (or with partial) upstream artifacts. Opening move: inventory the existing system, then produce the missing upstream deliverables — a light retro-framing, an architecture note reconstituted by observation, and retroactive ADRs that record the structuring choices already made and the signal under which to reopen them. With the map drawn, enter the chain at the current tier.
+- **M3 — Audit then rebuild.** The system was not built on these principles. Opening move: a principled audit, a gap analysis section by section, then a rebuild plan. The rebuild is never one block; it follows the brownfield procedure below.
+- **M4 — Derive a new system from an old one.** The existing system is an input and a legacy constraint, not a base to copy. Opening move: frame the new system using the old one as a source of requirements and constraints, then enter the chain as greenfield from `frame`.
+
+**Apply the brownfield procedure (M3 and M4).** On legacy, the boundary is not given and is never free — integration cost concentrates exactly there. Three moves, in order, never skipped:
+
+1. **Characterize before touching.** Capture the real behavior of the existing system, quirks included, with characterization tests before any modification. Find the seams — the points where behavior can be altered without rewriting. Until behavior is captured, do not rebuild: you would silently break what worked.
+2. **Install an anticorruption layer.** An adapter at the boundary translates the legacy dialect into the clean domain language and stops the old model from contaminating the new. The new domain stays pure behind that boundary.
+3. **Replace progressively, strangler-style.** Build the new around the old, unplug it feature by feature on proof, until the old retires naturally. Never a single-shot cutover. Each replacement is guarded, measured, and reversible behind the boundary.
+
+**Lock and re-enter.** Every structuring choice discovered or taken on the existing system — what is kept, what is rebuilt, where the anticorruption boundary runs — is locked as an ADR via `decision-loop`, retroactive ADRs included. Then re-enter the `method` chain at the right phase: usually `architect` for M2 and M3, `frame` for M4, the current phase for M1. Governance, iteration, and handover proceed unchanged.
+
+## Definition of Done
+
+- Entry mode chosen explicitly with the sponsor.
+- Missing upstream artifacts produced (retro-framing, reconstituted architecture note, retroactive ADRs).
+- For rebuilds: behavior characterized, anticorruption layer in place, replacement plan staged feature by feature.
+- Chain re-entered at a named phase, with the same gates as greenfield.
+
+## Anti-patterns
+
+- Rewriting in one block — the mass cutover is forbidden.
+- Modifying behavior that has not been captured.
+- Confusing audit with rebuild: the audit establishes the gap, factual and sourced; the rebuild is a separate, guarded, progressive decision.
+- Resuming a mission from memory instead of its artifacts.
+- Pretending the boundary is free on legacy — name the translation cost and budget it.
+- Copying the old system instead of treating it as requirements and constraints.

package/templates/workflows/decision-loop.md

@@ -0,0 +1,52 @@
+# Decision Loop — Lock a Position Before Touching the Document
+
+## When to use
+
+Use this workflow whenever a durable technical position must be decided before editing an architecture document or committing a design: "should we change this?", "does this critique hold?", "what is the right practice here?", "add this idea to the doc". It pairs with `review`, which provides the expert eyes; this workflow provides the method. The rule that dominates everything: challenge and ask before any modification. Never edit on instinct, never edit before the lock.
+
+## Inputs
+
+- The critique, requirement, transcript, or doubt that triggered the loop.
+- The document or design under question.
+- Access to the real code that implements (or will implement) the system, or to public reference implementations.
+
+## Outputs
+
+- A locked design note in ADR form.
+- A validated edit plan — and only then, edits.
+
+## Procedure
+
+**Hold the governing principle.** The document standardizes best practice, not the current state of the code that implements it. Check the code for reality, confront the state of the art for reference, then write the best defensible version — without ever exposing the code's limitations in the document. If the code is not yet up to standard, the code catches up; the document never stoops to the code.
+
+**Run the loop, in order, for every critique, doubt, or proposed addition.**
+
+1. **Reality-check the code.** Read what the code already does today in the repositories that carry the system. Identify what is implemented, partial, or absent. On greenfield, reality-check against public reference implementations and established architectures instead. These findings calibrate the position; they are never quoted in the document.
+2. **Source the state of the art.** Hunt for evidence: research papers, leaders' documentation, standards, audits. Search, then read the sources. Never lock a position on intuition — anchor it on nameable sources. If an angle stays blurry, dig before locking.
+3. **Challenge the source.** Confront the critique or requirement with what you just learned. Keep what has real merit; discard noise, passing fads, and overclaims. Distinguish the timeless pattern from the fashion of the season.
+4. **Take a durable position.** Decide: what is the standard, defensible stance that would hold in front of a regulated-sector architecture committee? Formulate the general rule, not just the one-off answer.
+5. **Lock it in writing.** Freeze the decision in a design note before any edit to the document. Not locked, not validated — not edited.
+6. **Write the lock as an ADR.** Three sections: **Context** (the problem, what the code already does, the sourced state of the art), **Decision** (the position taken and the alternative discarded), **Consequences** (effects, plus the precise spec of the edits: which sections, which additions). Precise vocabulary, no hedging, no subjective escape hatches. The edit spec is validated before anything is written. Use `mission/adr/ADR-0000-template.md`.
+7. **Integrate, in strict order.** First the blocking fixes — propagation of already-locked decisions for consistency, no new design. Then the important design questions, each by rerunning this full loop. Then a whole-document consistency pass — the entire document, not section by section. Minors last.
+
+**Apply the golden rules throughout.** Ask before modifying, always. Never write before the lock. Standardize best practice; never expose the code's internal constraints in the document. Source every state-of-the-art claim. Distinguish the durable pattern from the passing fad. Watch for overlapping decisions: when two designs touch, reconcile them in one transition, never as two parallel mechanisms. End every cycle with whole-document consistency, never only local.
+
+**Articulate with the review panel.** In practice: `review` spots a finding through its six-criterion grid and grades it blocking / important / minor. If the finding is a genuine design question, this loop runs (steps 1–6). Then integration happens (step 7), and the panel repasses for whole-document consistency. Both workflows share one golden rule: the reviewer criticizes and the loop decides — nobody rewrites without validation.
+
+**Name the artifacts predictably.** In the mission's decision folder (for example `decisions/` or `adr/`): a dated triage of retained critiques; one dated, locked design note (ADR) per decision; a dated record of panel verdicts; a dated consolidated edit plan.
+
+## Definition of Done
+
+- Every triggered question ran the full loop in order — no step skipped.
+- One locked ADR per decision, with sourced context and a discarded alternative.
+- The edit spec validated before any edit.
+- Integration done in order: blocking, important (with loop), whole-document consistency, minors.
+
+## Anti-patterns
+
+- Editing the document first and justifying afterward.
+- Locking a position on intuition, without nameable sources.
+- Quoting the code's current limitations in the document.
+- Adopting a passing fad as if it were a durable pattern.
+- Running two parallel mechanisms where two decisions should have been reconciled into one.
+- Skipping the whole-document consistency pass after local edits.

package/templates/workflows/floor.md

@@ -0,0 +1,60 @@
+# Floor — Ship the Smallest System That Proves Value
+
+## When to use
+
+Use this workflow once the architecture is fixed and building must start: "what do we code first?", "we need an MVP", "should we add memory / multi-agent now?" (answer: not without a trigger). This is phase 3 of `method`. It delivers the floor: the smallest system that proves value on real traffic — a running system, not a demo.
+
+## Inputs
+
+- The architecture note, port list, and integration protocol from `architect`.
+- The observable success criterion from `frame`.
+- Real model access, real inputs, and a hook into the existing infrastructure.
+
+## Outputs
+
+- A running floor wired to real traffic.
+- A floor note (use `mission/floor.md`): scope, measured proof, gaps, next tier.
+
+## Procedure
+
+**Enforce the entry rule.** The floor plugs into real traffic and existing infrastructure. Anything not required to prove value is deferred and attached to an explicit trigger. A component without a trigger does not enter the floor.
+
+**Start from the reference floor, not a blank page.** The starting point is the reference floor (`floor-ts/` in the Runward repository): a clonable hexagonal scaffold that already carries the pure domain, the ports, the adapters, and the middleware chain, with a principle-to-code table mapping each principle to where it lives in the code. Clone it, implement the project's concrete adapters behind the ports fixed in `architect`, and leave intact the structure that keeps the domain testable without the model. Do not reinvent the skeleton; populate it.
+
+**Build exactly these six pieces, and nothing more.**
+
+1. **An entry point matched to actual use.** A minimal interface when a human operates the system (submit, review, approve, decide); an API or tool protocol when another system drives it. It is a primary adapter — plain, replaceable, never touching the domain, and never a demo showcase.
+2. **A single orchestrator.** It runs the loop: plans, delegates, synthesizes. It composes; it carries no business logic.
+3. **A model port behind a direct SDK.** Thin abstraction, one balanced tier, no heavy chain framework. The model port is the heart of the floor, not a deferred item: ship a real, provider-agnostic adapter that activates as soon as a key is configured, with a deterministic fallback when none is. The app must run for real by filling in configuration — never stay in simulation by default. The adapter names no provider; provider quirks (headers, required fields) resolve at assembly time through a profile, never inside the domain.
+4. **Persistence.** An immutable interaction log as the source of truth, attached to a business entity. The agent is a reducer with no hidden state: each turn acts on explicit context and produces explicit state.
+5. **Guardrails in code.** Everything that can be deterministic — classification, validation, access control on mutations — leaves the model for testable code. The model only reasons.
+6. **Baseline observability.** Structured logs (one line per event, typed context), persisted lifecycle events, and a request ID propagated from the entry point to every tool and model call. This is what makes a trajectory replayable and auditable later.
+
+**Resist everything else.** Until an objective trigger fires, the floor has no elaborate memory (default: explicit per-turn context, minimal retrieval), no multi-agent (default: one orchestrator, specialists in-process), no externalized state (default: in-memory, single instance), and no crossed process boundary (a sidecar only when a mature library in another ecosystem demands it). These deferrals are not omissions: each is named with its trigger and handled in `iterate` when the signal arrives.
+
+**Never defer two things.** The working model adapter, and baseline governance — observability, guardrails, and a simple per-run cost ceiling that stops and synthesizes on overrun. These are floor components, not later tiers. Deferral applies to memory, multi-agent, external state, and distribution — never to the fact that the app runs and is governed.
+
+**Prove the floor before declaring it done.**
+
+1. Wire it to real traffic or a representative sample — not to cases picked to impress.
+2. Measure against the success criterion fixed at framing. Without this measurement you cannot decide the next tier.
+3. Verify observability holds: a full trajectory reconstructs after the fact from its request ID. Without that, the system is ungovernable.
+
+Lock any structuring decision met during the build through `decision-loop`. Write the floor note and pass it through `review`.
+
+## Definition of Done
+
+- The floor runs on real traffic through the existing infrastructure.
+- Value measured against the observable success criterion.
+- A complete trajectory replays from a single request ID.
+- Every deferral named with its trigger.
+- Floor note produced and reviewed.
+
+## Anti-patterns
+
+- Shipping a demo and calling it a floor — a system that never touches real traffic proves nothing.
+- Leaving the model port in simulation mode by default.
+- Letting the model perform work that deterministic code can do.
+- Retrofitting observability after the fact — it always costs more.
+- Adding memory, agents, or distribution "while we're at it".
+- Freezing the target: its richness is earned tier by tier, never built in one block.

package/templates/workflows/frame.md

@@ -0,0 +1,69 @@
+# Frame — Decide the Perimeter Before Writing Code
+
+## When to use
+
+Use this workflow at the start of any agentic-system mission, or whenever the perimeter is fuzzy: "we'd like an agent that…", "what do we build first?", "do we need multi-agent / long-term memory?", "which language, which stack?" (answer: not yet). This is phase 1 of `method`. It turns a vague intent into a decided perimeter: what gets built first, what is explicitly deferred, and under which conditions complexity will be added.
+
+## Inputs
+
+- A sponsor and a real business problem.
+- Access to the people who run the process today.
+- The Definition of Ready checklist below.
+
+## Outputs
+
+- A framing note (use the `mission/framing.md` template).
+- The floor/target split with named deferrals.
+- Presumed architecture boundaries — ports and integration protocol, stack left open.
+
+## Procedure
+
+**Refuse stack questions.** If the conversation opens with framework, language, or provider, push it back: those are adapter decisions, reversible, taken later behind stable contracts. Framing decides the problem and the floor, not the technology.
+
+**Check the Definition of Ready.** Eight conditions in three families.
+
+- **Mandate**: a real problem with an identified sponsor; an observable success criterion; acceptance of the floor-first principle.
+- **Access**: to the real process and its people; to usable data or a path to it; to the technical infrastructure.
+- **Constraints**: hard constraints known (sovereignty, regulation, legacy integration); a human available to decide and approve sensitive actions.
+
+Treat these as a floor, not a barrier: a missing condition becomes a named risk, owned by the sponsor, and often the first object of discovery — it is not a compliance turnstile.
+
+**Establish entry mode and stopping tier first.** Present both as explicit choices to the sponsor: where the work starts (greenfield, or an existing system — in which case route through `brownfield` first) and how far it goes (framing, floor, full chain). Detail lives in `method`.
+
+**Run discovery in five question families, in order.**
+
+1. **The real process.** How does it actually happen today — frictions, manual rework, waiting? Hunt the observed process, not the idealized one.
+2. **The value.** Where is value created if this works? Time saved, errors avoided, quality raised, new service? Who benefits, how often?
+3. **The success criterion.** What observable, measurable fact would say "it works" on real traffic? Reject impressions.
+4. **The data.** What comes in, what goes out, from where, to where? Sensitive data, expected traceability.
+5. **The hard constraints.** Sovereignty, regulated sector, legacy integration, confidentiality, mandatory human approval. These bound the solution space; tool preferences do not.
+
+**Split floor from target.** The floor is the smallest system that proves value on real traffic — typically a single orchestrator, a model port, persistence, a few guardrails, baseline observability, nothing more without a trigger. The target is the full architecture you are heading toward — elaborate memory, multi-agent, externalized state, distribution, continuous evaluation. Name the target to set direction; do not build it up front. Every deferral is written down with the trigger that will reactivate it.
+
+**Apply the upstream decision matrix.** For each structuring choice, record a lean default and the objective trigger that commands a switch. Apply the default; switch only on signal.
+
+- **Topology**: default single agent; trigger — genuinely independent, parallelizable subtasks.
+- **Memory**: default explicit per-turn context; trigger — a measured need for cross-session continuity.
+- **State**: default in-memory, single instance; trigger — replication or cross-process sharing.
+- **Process boundary**: default one process; trigger — a capability whose lifecycle, ecosystem, or scale truly differs.
+- **Model tier**: default one balanced tier; trigger up — measured quality demands it; trigger down — deterministic tasks routed cheaper.
+- **Determinism**: default — everything that can be deterministic (classification, validation, guardrails) leaves the model for testable code; the model only reasons.
+- **Untrusted input and privilege**: default — retrieved content is data, never instruction; least privilege; human approval on sensitive actions. In regulated sectors this is a framing constraint, not a late add-on.
+
+Lock any truly structuring decision through `decision-loop` before committing it to the note.
+
+## Definition of Done
+
+- Framing note produced: problem, value, observable success criterion, hard constraints — one page.
+- Floor perimeter listed, every deferral named with its trigger.
+- Presumed boundaries stated; language and topology explicitly left open.
+- Note reviewed via `review` before circulation.
+- Deliverable form matched: the presented note carries an expected delivery form (a readable PDF or HTML); engineering artifacts stay as repository markdown.
+
+## Anti-patterns
+
+- Deciding the stack during framing.
+- Accepting a fuzzy success criterion — without it, the floor can never be proven.
+- Padding the floor with untriggered features.
+- Discovering a sovereignty or compliance constraint after the floor is built.
+- Declaring the phase done without its artifact, silently.

package/templates/workflows/govern.md

@@ -0,0 +1,55 @@
+# Govern — Trust Through Instrumentation, From Day Zero
+
+## When to use
+
+Use this workflow whenever a system must be made reliable, auditable, or safe: "how do we secure this?", "we need observability", "how do you test an agent?", "do we add human approval?", "how do we stop prompt injection?". This is phase 5 of `method` and it is transversal: it starts at day zero of phase 3, wired onto the floor and maintained at every tier — never after the incident. Trust is built by instrumentation; retrofitting always costs more.
+
+## Inputs
+
+- A floor (or later tier) with its middleware chain and tool registry.
+- The `mission/threat-model.md`, `mission/evaluation-rubric.md`, and `mission/observability-schema.md` templates.
+
+## Outputs
+
+- A single instrumented middleware chain.
+- A threat model, an evaluation rubric with hold-out, an observability schema.
+- Cost ceilings and approval points live in production.
+
+## Procedure
+
+**Route all transversal concerns through one middleware chain** on the tool registry — never scatter them.
+
+- **Structured logging**: one line per event, typed context, plus persisted lifecycle events and per-model-call metrics (tokens, tier, duration, status).
+- **Propagated request ID**: from entry to every tool and model call, and down to sub-agents through parent/child lineage — the thread that reconstructs a full trajectory.
+- **Provenance**: per inference, keep a fingerprint of what was actually injected, so you can replay what the model saw even after working memory is gone.
+- **Cost control**: the model boundary (deterministic work pays no model call), tier routing, caching, and explicit ceilings per root task and per time window — from day zero. On overrun the orchestrator stops and returns a synthesis instead of running open-ended.
+- **Approval point**: tools with impact declare in their contract that they require approval. The guard is enforced by infrastructure, never by the model's discipline.
+
+The chain carries transversal concerns only — no orchestration, no business logic. Keep the channel thin and the registry an index. One trace stream feeds provenance, observability, and evaluation separately.
+
+**Keep the interactive turn thin — and govern the background like the foreground.** The turn does only what the answer needs; everything else (fact extraction, memory consolidation, episode summaries, context pre-warming) leaves the turn for an event-driven post-turn pipeline: each step isolated with its own bounded retry, one step's failure never failing the others, the provenance fingerprint deposited at emission. Periodic upkeep — score decay, pruning derived links past retention, cold-archiving old journal segments, trend detection, reminders, enforced erasure — belongs to a scheduled cron that updates and cools but never destroys the truth. Every background job carries four non-negotiable guardrails: bounded retry per step; idempotency (keys plus atomic deduplication, including under concurrency); bounded concurrency (a global cap and a per-user partition); and job observability — queue lag and failure rate are first-class metrics. The craft rules `async-post-turn-pipeline`, `async-scheduled-maintenance` and `async-job-guardrails` carry the detail.
+
+**Make resilience the default.** Qualify every failure first, because the response depends on the type: transient — bounded exponential-backoff retry; validation — one retry with the diagnostic fed back; business — diagnosis or human escalation; model provider down — automatic fallback behind the same port; non-critical service down — a signaled degraded mode. Then apply the rule: **fail-open on reads, fail-closed on actions.** Cache, observability, enrichment degrade silently; a sensitive action (mutation, write, external push) fails closed and explicit rather than executing in doubt. Degrade reading, never acting. Add feature detection at startup: a minimal mode that runs on the strict necessary, a full mode when all dependencies are present, and an interface that says what is active instead of failing silently.
+
+**Constrain security by architecture, not detection.** Prompt injection is the first-rank threat, intrinsic to any memory or retrieval; detection is unreliable, so defend structurally: retrieved content is data, never instruction; least privilege on tools (registry filtered by role before the model sees it); ownership guards before mutations; schema validation on outputs; an immutable log that keeps every injected action traceable. Apply the **lethal trifecta** rule: while untrusted content is in the context window, allow at most **two of three** — private data access, untrusted content, external communication; if all three are needed, the action runs under human supervision. The window opens at ingestion and closes only when the content is purged. For high-privilege agents, add dedicated patterns: pre-approved action sets, a plan frozen before exposure to tool outputs, quarantine of untrusted content, or a privileged planner split from a read-only model. Approval summaries are deterministic and faithful to the tool's real arguments — never a model paraphrase. An awaiting-approval agent suspends: state serialized durably, resources freed, rehydrated when the decision arrives.
+
+**Test and evaluate — both.** Build the test pyramid: unit tests without network (pure domain, mocked model adapter); consumer-driven contract tests that catch drift between schema and real data; integration through the injection container with mock adapters; behavioral evaluations at the top. Then run the continuous evaluation loop: sample the trace stream off the hot path; score hybrid — deterministic checks wherever a guarantee exists, an anchored judge model (pinned version or replayed anchor set) only for the irreducibly behavioral, abstention first. The loop is valid only under a **hold-out the optimizer never sees**; self-tuning stays inside a pre-approved, audited envelope or goes through human validation — never autonomous self-rewriting. The hard floor — safety, security, authorization, audit — stays deterministic; never assemble it from soft judgments. Promote a new model via shadow deployment: same port, real traffic, silent; measure divergence with the same evaluation; roll out in stages with instant rollback.
+
+## Definition of Done
+
+- All transversal concerns pass through the single middleware chain; a trajectory replays from one request ID.
+- Cost ceilings enforced with stop-and-synthesize behavior.
+- Threat model written; two-of-three trifecta rule enforced while untrusted content is in the context window.
+- Test pyramid in place; evaluation loop running with anchored judge and hold-out.
+- Background work guarded: pipeline steps isolated and idempotent, the maintenance cron never deletes truth, queue lag and failure rate alerting in place.
+
+## Anti-patterns
+
+- Postponing instrumentation until after the first incident.
+- Treating the model as a trust boundary — once untrusted content is ingested, the action space must narrow.
+- Letting the model write its own approval summaries.
+- Closing the evaluation loop without a hold-out: it drifts toward flattering the judge.
+- Handing the hard floor to a judge model.
+- Failing open on a sensitive action.
+- Running consolidation, extraction or summarization inside the interactive turn — the user pays latency for work the answer does not need.
+- A cleanup cron that deletes from the immutable journal.