runward

RW™ · V0.22.0

Docs · Understand · The six phases · In detail

The six phases in detail.

Frame, architect, floor, iterate, govern, hand over: the deliverable and definition of done that runward checks at each gate, phase by phase.

Phase 1 — Frame

Required deliverables: the Framing note (runward/framing.md) and the Steering contract (runward/mission-contract.md).

What it produces

Frame turns a vague intent into a decided perimeter: what gets built first, what is explicitly deferred, and under which trigger complexity is added later.

Discovery runs in five ordered question families:

  1. the real process
  2. the value
  3. an observable success criterion
  4. the data
  5. the hard constraints

The steering contract ties that criterion to the deliverables and to what closes each engagement. Stack questions are explicitly refused here — language and topology stay open.

Definition of done

  • framing note produced (one page: problem, value, observable success criterion, hard constraints)
  • steering contract filled with the sponsor
  • the floor perimeter listed with every deferral named against its trigger
  • presumed boundaries stated with language and topology left open

What the gate checks

Both files must reach filled — i.e. materially diverge from their templates and drop below three placeholders. There is no --strict rule manifest for Frame (it is absent from GATED_DELIVERABLES). The gate confirms the two artifacts exist and are genuinely written; it does not judge whether the success criterion is good.

Phase 2 — Architect

Required deliverables, five of them: the Architecture note (architecture.md), the Execution topology (execution-topology.md), the Decision matrix (decision-matrix.md), the Decision journal (adr/, at least one real ADR), and Port contracts (contracts/, at least one filled).

What it produces

Boundaries before stack: domain ports, the model port as a port like any other, and the cross-process integration protocol — with language and topology deliberately open.

A second, parallel vision is recorded in execution-topology.md: one row per port giving its adapter, location family, data class(es), sovereignty level, and the trigger to move it. Any non-in-app placement is an ADR. runward traces this placement decision; it never deploys.

Definition of done

  • architecture note produced boundaries-first
  • decision matrix adopted (each structuring choice with a sober default and objective trigger)
  • every port named with a contract and initial version
  • the execution-topology note produced with each port placed
  • one ADR per structuring choice, locked before the note mentions it
  • every architect CRITICAL/HIGH rule accounted for in the conformance manifest

What the gate checks

  • Presence — all five artifacts must be filled. Two use special counting: the ADR directory is filled only when it holds a real ADR-<n>-*.md beyond the ADR-0000-template.md; the contracts/ directory is filled as soon as one .md differs from the raw port-contract template.
  • Strict rule conformance — two scopes run: architect/architecture.md and topology/execution-topology.md. Each must carry a ## Rule conformance markdown table that accounts for every CRITICAL/HIGH rule mapped to that phase in runward/rules/ frontmatter. Each such rule needs a row with status applied (+ an evidence pointer), deviated (+ an ADR that actually exists in runward/adr/), or n/a (+ a real reason, not a placeholder).
  • Non-vacuity floor — the mapping cannot be silently stripped to make the gate pass on nothing: architect must keep at least 6 mapped rules and topology at least 4; dropping below raises a (mapping) violation.
  • Drift — an applied pointer whose file path no longer resolves is a blocking gap under --strict.
  • Unratified ADRs — a reconstructed decision still marked DRAFT-, Status: hypothesis, or why: UNKNOWN fails the strict gate: an agent's guess must not pass as a decision.

Phase 3 — Floor

Required deliverable: the Floor note (runward/floor.md) — "measured proof".

What it produces

The smallest running system that proves value on real traffic — a running system, not a demo. The workflow prescribes exactly six pieces and nothing more:

  • an entry point
  • a single orchestrator
  • a model port behind a direct SDK (with a deterministic fallback so the app runs for real once a key is set)
  • immutable persistence
  • guardrails in code
  • baseline observability with a propagated request ID

The starting point is the shipped reference floor floor-ts/ — a clonable hexagonal scaffold (a pure, modular core behind ports, adapters at the edges) you populate, not reinvent. Hexagonal is the method's sober default, not a requirement: the gate checks the decision was confronted, and deviating with a traced ADR passes green.

Definition of done

  • the floor runs on real traffic through existing infrastructure
  • value measured against the observable success criterion
  • a complete trajectory replays from a single request ID
  • every deferral named with its trigger
  • every floor CRITICAL/HIGH rule accounted for
  • floor note produced and reviewed

What the gate checks

  • Presencefloor.md must be filled.
  • Strict conformance — the floor scope must account for every floor-mapped CRITICAL/HIGH rule, with a non-vacuity floor of 10 mapped rules. The floor note is where typed evidence pointers are strongly preferred — file:PATH[:LINE][#SYMBOL], test:PATH[::NAME], adr:NNNN — which the evidence layer verifies deterministically for resolution and content, plus the rule's declared signature: regex when present.
  • Behavioral proof (advisory, above the gate) — when the strict gate is otherwise green, runward reads an optional Behavioral proof: <command> (and optional Proof artifact:) declared in floor.md and reports the artifact's presence and freshness only — it never runs the command or reads a verdict. This is the explicit boundary: the gate is the documentary proof that decisions are traced; the behavioral proof is your test suite. runward is not a runtime.

Phase 4 — Iterate

Required deliverable: none as a fixed file — and that is by design. Iterate is a real phase in the method but has no entry in the gap-analysis PHASES and no entry in GATED_DELIVERABLES. Its output is instead one locked ADR per switch, each with a reevaluation/rollback trigger.

What it produces

Evolutions added only on an objective trigger or a measured gain — never "because it's more modern". The workflow supplies a decision matrix of the common switches, each with a sober default and the signal that commands the change:

  • extract a service
  • add an agent
  • change model tier
  • cross a process boundary
  • add elaborate memory
  • externalize state
  • go async

Definition of done

  • every shipped evolution maps to an observed trigger or measured gain
  • one locked ADR per switch including the rollback signal
  • the domain untouched (only adapters and topology move)
  • execution-topology.md reopened and updated for any switch that moved a port's placement
  • post-switch measurement recorded, rollbacks executed where the gain failed

What the gate checks

Indirectly, through the artifacts iterate touches. Each new ADR is subject to the same ratification lifecycle — a DRAFT-/hypothesis/why: UNKNOWN ADR fails --strict. If an iteration moves a placement, the updated execution-topology.md is re-checked by the topology strict scope. There is no standalone "iterate gate": the discipline is enforced where the changes land.

Phase 5 — Govern (day zero)

Required deliverables, three, all under governance/: the Threat model (governance/threat-model.md), the Evaluation rubric (governance/evaluation-rubric.md), and the Observability schema (governance/observability-schema.md).

What it produces

Govern is transversal: it starts at day zero of the floor and is maintained at every tier, never bolted on after an incident. It:

  • routes all cross-cutting concerns through a single middleware chain (logging, request-ID propagation, provenance, cost ceilings with stop-and-synthesize, approval points),
  • makes resilience the default (fail-open on reads, fail-closed on actions),
  • constrains security by architecture (the "lethal trifecta" two-of-three rule while untrusted content is in context),
  • and runs a continuous evaluation loop under a hold-out the optimizer never sees.

Definition of done

  • all transversal concerns pass through the single chain and a trajectory replays from one request ID
  • every govern CRITICAL/HIGH rule accounted for
  • cost ceilings enforced with stop-and-synthesize
  • threat model written with the two-of-three trifecta rule enforced
  • the test pyramid and evaluation loop in place with anchored judge and hold-out
  • background work guarded

What the gate checks

  • Presence — all three governance files must be filled.
  • Strict conformance — the govern scope reads its manifest from governance/threat-model.md and must account for every govern-mapped CRITICAL/HIGH rule, with the highest non-vacuity floor of any phase: 12 — reflecting that governance carries the most safety/security-critical rules. Same row rules apply (applied/deviated/n/a), same drift and ADR-ratification checks.

Phase 6 — Hand over

Required deliverables: the Recovery runbook (runward/runbook.md) and the Hand-over note (runward/handover.md, "the kit, proven").

What it produces

Autonomy, not dependency: the phase is proven only when the receiving team repeats a real task alone, end to end. The hand-over note:

  • indexes a six-part kit (reusable assets, architecture note, ADR journal, runbook, proof in code, and the finalized harness-neutral AGENTS.md charter),
  • records the redone-task proof,
  • names the succession,
  • and logs a provider-swap drill.

Definition of done

  • kit complete including the finalized AGENTS.md
  • hand-over note produced with kit index, redone-task proof, succession named, provider-swap drill logged
  • every handover CRITICAL/HIGH rule accounted for
  • transfer sessions held with the team operating (not watching)
  • at least one real task repeated alone and recorded

What the gate checks

  • Presencerunbook.md and handover.md must both be filled.
  • Strict conformance — the handover scope reads handover.md and must account for every handover-mapped CRITICAL/HIGH rule, non-vacuity floor 4, down to typed evidence pointers.
← Docs