runward 0.6.0

package/templates/workflows/handover.md

@@ -0,0 +1,55 @@
+# Handover — Leave Autonomy, Not Dependency
+
+## When to use
+
+Use this workflow when a delivery approaches its end or a team must become self-sufficient: "how do we hand this off?", "we need to document for the team", "how do they run this without us?". This is phase 6 of `method`. What the operator leaves behind counts as much as what was delivered: a deliverable that creates lasting dependency on its author is a failure of this phase.
+
+## Inputs
+
+- The artifacts of prior phases: architecture note, floor, ADR journal, threat model, evaluation rubric, observability schema.
+- A receiving team with time allocated for transfer sessions.
+- The `mission/runbook.md` template.
+
+## Outputs
+
+- A handover kit (below).
+- A demonstrated proof of autonomy.
+
+## Procedure
+
+**Enforce the entry rule.** You transfer autonomy, not documents. Handover is not a folder delivered; it is proven by the team repeating a task alone. Until that proof exists, this phase is open.
+
+**Assemble the handover kit.** Five components:
+
+1. **Reusable assets.** The populated scaffold, the adapters, the versioned contract schemas, the evaluation sets. Things that replay and get reused, not just things that get read.
+2. **The architecture note.** Boundaries, ports, integration protocol, the named target, and the default topology with its triggers. The map that says why the system is shaped this way.
+3. **The ADR journal.** Every structuring decision locked in Context / Decision / Consequences form, with the discarded alternative and the reevaluation trigger. The team learns not only what was decided, but under which signal to reopen it.
+4. **The operations runbook.** How to start, observe, debug, resume from a checkpoint, switch a model provider, rerun the evaluation bench, process a suspended approval. Operating gestures, not theory. Use `mission/runbook.md`.
+5. **Proof in the code.** Unit and contract tests, evaluation scenarios, replayable traces — the demonstration that the principles are not speculative; they live in the code.
+
+**Run the transfer, don't just deliver it.**
+
+1. **Transfer sessions.** Walk the team through the architecture, the decisions, and the runbook — hands on the keyboard, not eyes on slides. Make them operate, not watch.
+2. **Readable notes.** Short, decided, accessible to whoever inherits the system.
+3. **Progressive withdrawal.** The team repeats a task first with you present, then alone. Step back as autonomy is proven, not on a calendar date.
+
+**Capitalize upward.** What repeats deserves standardizing. Escalate recurring patterns to whoever can industrialize them: an evolution trigger observed several times, an adapter rewritten identically across missions, a recurring guardrail. Feed proven arbitrations back into the decision matrix and the workflow files — the corpus hardens mission after mission. What gets capitalized is never the prototype (replaceable); it is the architecture and the method (owned).
+
+**Verify the Definition of Done explicitly.** The phase is done when the receiving team redoes a task alone, end to end, demonstrated — a sign-off or a training session does not count. The team, without you: starts the system, observes it, debugs an incident, adds an evaluation scenario, and decides a switch by leaning on the ADRs. All of it demonstrated, not promised.
+
+## Definition of Done
+
+- Handover kit complete: assets, architecture note, ADR journal, runbook, proof in code.
+- Transfer sessions held with the team operating, not observing.
+- The team has repeated at least one real task end to end, alone — demonstrated, witnessed, recorded.
+- Recurring patterns escalated and fed back into the framework's templates.
+- Deliverable form matched: presented notes carry an expected delivery form (a readable PDF or HTML); ADR journal, runbook and code proofs stay as repository markdown.
+
+## Anti-patterns
+
+- Creating lasting dependency on the operator — if the team can do nothing without them, handover failed.
+- Handing over only the prototype: the prototype is replaceable; the architecture and method are what transfer.
+- Delivering a document without walking it through — a note handed over is not a skill transferred.
+- Closing the phase on a signed deliverable instead of a task repeated alone.
+- Keeping recurring patterns to yourself instead of feeding them back.
+- Padding the kit with theory the team will never operate from — runbooks carry gestures, not lectures.

package/templates/workflows/iterate.md

@@ -0,0 +1,52 @@
+# Iterate — Add Complexity Only on Proof
+
+## When to use
+
+Use this workflow once a floor is running and an evolution is on the table: "do we go multi-agent?", "should we extract this service?", "do we raise the model tier?", "do we add long-term memory?", "how do we scale?". This is phase 4 of `method`. Every switch has a lean default and a signal that commands the change; every evolution is guarded by a boundary and traced in an ADR.
+
+## Inputs
+
+- A proven floor: value measured against the success criterion.
+- Real traffic over time — the source of trigger signals.
+- The decision matrix below; the ADR template in `mission/adr/`.
+
+## Outputs
+
+- Evolutions shipped one tier at a time, each behind its boundary.
+- One locked ADR per switch, with the reevaluation trigger.
+
+## Procedure
+
+**Enforce the entry rule.** No evolution without a signal. "Because it's better", "because it's more modern", "because we'll need it" are refused. Name the default in place, name the trigger, switch only when the trigger is observed on real traffic.
+
+**Arbitrate with the decision matrix.** Apply the default, watch the signal, switch on proof.
+
+- **Extract a component into a service.** Default: modular hexagonal monolith. Triggers: one instance no longer holds the load; a component has a sharply different load or cost profile; it needs its own release cycle; isolation is required for resilience or security; high availability is demanded. Boundaries being set, extraction is a local operation, not a rework.
+- **Add an agent.** Default: one orchestrator directing specialists. Trigger: genuinely independent, parallelizable subtasks — not sequential reasoning in disguise. Distributed multi-agent wins on parallelizable work and degrades sequential reasoning; give it the same caution as microservices.
+- **Change the model tier.** Default: one balanced tier, routing by estimated complexity. Trigger up: a task whose measured quality demands it. Trigger down: a deterministic task routed to a cheaper tier. In doubt, go one tier up rather than risk a wrong answer.
+- **Cross the process boundary.** Default: as late as possible. Crossing changes semantics: an atomic local access becomes a network call, and three real costs are assumed — eventual consistency instead of strong; compensation steps instead of a single transaction; explicit causal ordering and idempotence under concurrency. That is the entry price of distribution — pay it only on trigger, knowingly.
+- **Introduce elaborate memory.** Default: explicit per-turn context, minimal retrieval. Trigger: a measured, not anticipated, need for continuity beyond the session. Then compose role-specific stores behind ports, with deterministic staged retrieval, value scoring, invalidation rather than deletion, and heavy work moved out of the interactive turn.
+- **Externalize state for multi-instance.** Default: in-memory structures, single instance. Trigger: replication (load, availability) or shared state. The shared store that unlocks multi-instance then hosts, at once, the externalized state, the capability discovery registry, and the budget allocation registry.
+- **Go asynchronous.** Default: synchronous work inside the turn. Trigger: costly operations that must not keep the user waiting (fact extraction, consolidation, summaries) move to background jobs fired after the turn.
+
+**Guard and trace every switch.**
+
+1. **Lock the decision in an ADR before implementing.** Run `decision-loop`: reality-check, sourced state of the art, challenge, durable position, written lock. No lock, no code.
+2. **Keep the evolution behind a boundary.** An extraction goes through the port already in place; a new agent through the registry; a tier change through the model gateway. The domain does not change; only the adapter and the topology do. Nothing here is irreversible, because everything is decided behind a boundary.
+3. **Prove the gain after the switch.** Load holds, latency drops, quality rises, cost stays controlled. If the gain is not there, roll back — the boundary makes rollback possible.
+
+## Definition of Done
+
+- Every shipped evolution maps to an observed trigger or a measured gain.
+- One locked ADR per switch, including the rollback signal.
+- The domain untouched; only adapters and topology moved.
+- Post-switch measurement recorded; rollbacks executed where the gain failed.
+
+## Anti-patterns
+
+- Complexifying on principle: memory, multi-agent, or distribution "because serious systems have them".
+- Crossing a gate without proof from the previous tier.
+- Dressing sequential reasoning up as parallelism to justify multi-agent.
+- Paying the distributed-systems entry price blindly — eventual consistency, compensation, causal ordering are the fee, not a footnote.
+- Implementing before the ADR is locked.
+- Switching without a rollback path.

package/templates/workflows/method.md

@@ -0,0 +1,53 @@
+# Method — Orchestrate the Six Phases
+
+## When to use
+
+Use this workflow whenever an agentic-system mission needs to be planned, advanced, or unblocked: "where do we start?", "what do we do next?", "are we ready for the next step?". This is the conductor. It sequences six gated phases and delegates the detail of each to its dedicated workflow (`frame`, `architect`, `floor`, `iterate`, `govern`, `handover`, plus `brownfield` for non-greenfield entries). Every design decision inside any phase runs through `decision-loop`; every document that matters runs through `review`.
+
+## Inputs
+
+- A sponsor with a real business problem.
+- Access to the process the system will serve.
+- The workflow files of this framework.
+
+## Procedure
+
+**Hold the posture before any phase.** Three rules outrank every tooling preference. Mentor as much as engineer — listening outranks solving: understand the process as it actually runs, not as it is described. Prove with a running system, not a deck. Decide architecture before models: the model and the infrastructure are adapter choices, reversible, made behind stable ports. The founding inversion underneath — the LLM Boundary Principle: the architecture constrains the model, never the reverse — opens the method; what carries it is the six phases, the **five architecture gestures** — boundaries before stack; isolate by contract and complexify on proof; take determinism out of the model; keep state explicit and memory governed; govern, trace and evaluate from day zero — and the decision matrix. These architecture gestures shape the system, and are not to be confused with the opening moves that start the mission (below).
+
+**Open the chain with four opening moves, in order, with the sponsor** — the mission's opening ritual, distinct from the five architecture gestures above. Together with show-before-you-build, they form four opening moves plus a standing show-before-you-build discipline.
+
+1. **Establish the entry mode.** Greenfield runs the chain below from the top. Anything else — resuming your own mission, joining a project in flight, auditing then rebuilding, or deriving a new system from an old one — goes through `brownfield` first, which reconstructs what is missing and re-enters the chain at the right phase. Never start on an existing system by instinct.
+2. **Establish the stopping tier.** How far does this engagement go: framing only, an executable floor, or the full chain through handover? Present each tier with what it produces and what it demands. The sponsor decides. Never pick the stopping point for them.
+3. **Derive the required inputs.** For framing: process access and an observable success criterion. For a proven floor: add real model access, real inputs, and a hook into existing infrastructure. For iteration and governance: sustained real traffic, traces, ground truth. For handover: a team to receive.
+4. **Challenge the gaps.** A missing input does not automatically block the start; it becomes a named risk, owned by the sponsor, and usually the first object of discovery. Say it out loud — never route around it silently.
+
+**Show before you build.** The standing companion to the four opening moves — repeated at every major gate, not a one-time step. Before committing work, show the sponsor a concrete preview of what they will receive: a sample deliverable, the artifact plan per phase, and — when the entry point is a user interface — an openable, working HTML first cut rather than a static mockup, functional even in deterministic mode. Repeat the preview at every major gate so the sponsor decides with open eyes.
+
+**Run the six phases, each behind a gate.**
+
+1. **Frame.** Light immersion in the real process. Output: the floor/target split and an observable success criterion. Delegate to `frame`.
+2. **Architect.** Boundaries before stack: domain ports, model port, integration protocol. Language and topology stay open. Delegate to `architect`.
+3. **Floor.** The smallest system that proves value on real traffic: one orchestrator, a model port, persistence, guardrails, baseline observability. Delegate to `floor`.
+4. **Iterate.** Add complexity only on an objective trigger or a measured gain, one ADR per switch. Delegate to `iterate`.
+5. **Govern.** Transversal, wired from day zero: single middleware chain, cost ceilings, human approval on sensitive actions, continuous evaluation. Delegate to `govern`.
+6. **Handover.** Leave autonomy, not dependency. Done when the team repeats a task alone. Delegate to `handover`.
+
+**Enforce the gate rule.** No phase closes without its prescribed artifact, and no gate is crossed without proof from the phase before it — value measured against the success criterion. Any deviation is stated explicitly and agreed with the sponsor, never assumed.
+
+**Match each deliverable to its form.** What is presented to a committee has an expected delivery form (a readable PDF or HTML); what is maintained stays as repository markdown, versioned with the code.
+
+## Definition of Done
+
+- Entry mode and stopping tier chosen explicitly by the sponsor, gaps named as owned risks.
+- A concrete preview shown before build and at each major gate.
+- Each phase closed with its artifact, or the deviation recorded and agreed.
+- No gate crossed without measured proof from the previous phase.
+
+## Anti-patterns
+
+- Starting with "which framework?" — that question belongs to an adapter decision, after boundaries. Return to phase 1.
+- Choosing the entry point or the stopping tier on the sponsor's behalf.
+- Building the full target in one block "to be serious about agents".
+- Deferring governance to a later phase; retrofitting always costs more.
+- Delivering a recommendation document instead of a running system.
+- Leaving the sponsor blind until delivery instead of showing before building.

package/templates/workflows/review.md

@@ -0,0 +1,59 @@
+# Review — Expert Panel for Architecture Documents
+
+## When to use
+
+Use this workflow to judge the technical soundness, internal consistency, and editorial quality of an architecture document for agentic systems — an architecture note, design note, RFC, spec, or whitepaper: "does this section hold?", "what would an architect say?", "is this state of the art?". This workflow provides the eyes; `decision-loop` provides the method. Pair them. Review is strictly read-only: the panel criticizes, it never rewrites without validation.
+
+## Inputs
+
+- The document under review.
+- Its intended audience (tech leads, engineering managers, CTOs, staff architects).
+- Any house editorial rules to enforce.
+
+## Outputs
+
+- Graded verdicts — blocking / important / minor — each with problem, evidence, and proposed fix.
+- A whole-document consistency pass.
+
+## Procedure
+
+**Calibrate the register first.** Such a document is usually neither an ML research paper, nor product documentation, nor code. It is applied software architecture for agentic systems, crossing five domains: software engineering (hexagonal, light DDD, event sourcing, evolutionary architecture, cost/reversibility reasoning); distributed systems (explicit state, scaling, consistency, resilience); applied LLM engineering (agent loop, tool use, model boundary, tier routing, memory and context, integration protocols); MLOps and evaluation (continuous evaluation, judge models and their biases, observability, drift, closed loops); governance and security (least privilege, human in the loop, fail-closed, data sovereignty, auditability). Review it with an architect's breadth, sharpened by specialist angles.
+
+**Adopt one Principal Architect wearing five hats** — distributed systems; LLMOps and production ML; memory and retrieval; security and regulated sectors; editorial coherence. Global mandate: uncompromising, strictly factual, zero complacency. Flag overclaims, blind spots, stale state of the art, cross-section inconsistencies, and anything that would not survive an architecture committee in a regulated sector.
+
+1. **Senior distributed-systems engineer.** Judges event sourcing, state externalization and projection, budget leases, service discovery, consistency, resilience, idempotence. Catches scaling naivety.
+2. **LLM platform engineer.** Judges evaluation (judge models, online evaluation, drift, Goodhart effects), observability, tier routing, cost, and the dangers of feedback loops — especially systems that rewrite themselves.
+3. **Applied research engineer in agent memory** (hardened by default). Judges bi-temporal memory, graph retrieval, decay and consolidation, context engineering, abstention, fact-conflict resolution.
+4. **Security and data-governance architect for regulated sectors** (hardened by default). Judges fail-closed behavior, human supervision, erasure and sovereignty, auditability, prompt injection, the lethal trifecta, untrusted inputs.
+5. **Technical editor of reference-grade material.** Judges structure, register, naming consistency, repetition, reading rhythm — with the same factual rigor. Enforces documentation-mode separation: do not mix tutorial, how-to, reference, and explanation in one section; an architecture note is explanation and reference, not tutorial.
+
+Rotate the hats one at a time over the same text, then reconcile their verdicts: a multi-persona pass aligns better with expert judgment than a single reviewer. Harden another angle on request.
+
+**Apply the six-criterion grid to every section.**
+
+1. Technical accuracy and state of the art — exact, current, defensible with sources in hand?
+2. Internal consistency — do cross-references hold (topology vs. async vs. evaluation; memory vs. state; decomposition vs. state)?
+3. Terminological precision — patterns named correctly, protocols described by function, vocabulary stable?
+4. Remaining overclaims and blind spots.
+5. Readability for the target audience.
+6. Compliance with the house editorial rules.
+
+**Neutralize known reviewer biases.** Self-preference: review generated-looking text with extra severity. Verbosity: longer is not better. Position and centrality: vary hat order between passes; prefer a binary holds / does not hold per criterion over a fuzzy scale. Separate substance from style: hats 1–4 judge correctness, hat 5 judges form.
+
+**Deliver graded verdicts.** For each finding: severity (blocking / important / minor), the problem, the evidence, the proposed fix. Discrete verdicts beat continuous scores — wide scales bias toward the center. Finish with a whole-document consistency pass, not only section-by-section. For any finding that demands a real design decision, hand off to `decision-loop` before anything is written into the document.
+
+## Definition of Done
+
+- Every section passed through all five hats and the six criteria.
+- Verdicts graded, each with problem, evidence, and fix.
+- A whole-document consistency pass completed.
+- Design-level findings routed to `decision-loop`; no edits made without validation.
+
+## Anti-patterns
+
+- Rewriting the document during review — the panel is read-only.
+- Scoring on a continuous scale instead of discrete verdicts.
+- Judging style and substance in one breath.
+- Skipping the whole-document pass and reviewing only locally.
+- Rewarding length or polish over correctness.
+- Softening verdicts because the author is in the room.