runward 0.19.0 → 0.21.0

package/README.md

@@ -1,28 +1,42 @@
 # Runward
 
-![Runward — the working frame for your agent, from idea to production](assets/og-image-en.jpg)
+![Runward — verify the engineering decisions behind AI-written code](https://raw.githubusercontent.com/stranxik/runward/main/assets/og-image-en.jpg)
 
-[![npm](https://img.shields.io/npm/v/runward?style=for-the-badge&color=0a0a0a&label=npm)](https://www.npmjs.com/package/runward) [![GitHub Marketplace](https://img.shields.io/badge/Marketplace-runward%20gate-2ea44f?style=for-the-badge&logo=github)](https://github.com/marketplace/actions/runward-gate) [![License: MIT](https://img.shields.io/badge/License-MIT-0a0a0a?style=for-the-badge)](LICENSE) [![Doctrine: CC BY-ND 4.0](https://img.shields.io/badge/Doctrine-CC%20BY--ND%204.0-C9A45C?style=for-the-badge)](https://github.com/stranxik/designing-and-running-agentic-systems) [![Support via Ko-fi](https://img.shields.io/badge/%E2%98%95%20Support%20via%20Ko--fi-orange?style=for-the-badge)](https://ko-fi.com/stranxik)
+[<img alt="npm" height="28" src="https://raw.githubusercontent.com/stranxik/runward/main/assets/npm-badge.png">](https://www.npmjs.com/package/runward) [![Docs](https://img.shields.io/badge/Docs-runward.dev-0a0a0a?style=for-the-badge)](https://runward.dev/docs) [![GitHub Marketplace](https://img.shields.io/badge/Marketplace-runward%20gate-2ea44f?style=for-the-badge&logo=github)](https://github.com/marketplace/actions/runward-gate) [![License: MIT](https://img.shields.io/badge/License-MIT-0a0a0a?style=for-the-badge)](LICENSE) [![Doctrine: CC BY-ND 4.0](https://img.shields.io/badge/Doctrine-CC%20BY--ND%204.0-C9A45C?style=for-the-badge)](https://github.com/stranxik/designing-and-running-agentic-systems) [![Support via Ko-fi](https://img.shields.io/badge/%E2%98%95%20Support%20via%20Ko--fi-orange?style=for-the-badge)](https://ko-fi.com/stranxik)
 
-**After the spec, the hard part starts. Runward ships it and runs it.**
+**AI writes the code. Runward verifies the engineering decisions behind it.**
 
-*The floor that keeps an agentic system alive. Run-grade engineering, from business need to production.*
+Your coding agent (Claude Code, Cursor, Codex…) is great at producing code. The harder question is who checks the decisions that make a system survive *after* the code ships — the architecture, where things run, how it's secured, how it's handed over.
 
-Your agent builds fast. Runward frames what it builds — six gated phases your agent executes and one human signs off — so what ships actually holds.
+Runward is an open-source delivery methodology for AI-assisted software engineering — a discipline made executable, not a library you import. It doesn't replace your agent; it gives it a way to work through a full engineering mission, from framing to handover, and then **verifies, deterministically**, that the load-bearing decisions were actually made and written down. Same input, same verdict; no prompt can talk it into passing.
 
-Runward is a delivery framework for agentic systems. It covers the entire mission, from framing to handover — it opens before any spec in greenfield, or picks up where the spec tools stop, and carries through to the run and the handover either way. Three ways in: day one of a new project (Frame is the first gate, before any spec exists), from an existing spec (Spec Kit, OpenSpec or in-house — it becomes the input of framing), or from an existing prototype (brownfield: characterize before touching anything). Then: floor first (the floor: the smallest *running* system that proves value on real traffic), evolution on evidence, governance from day zero, and a handover that makes your team autonomous.
+The core idea: don't ask an LLM whether the engineering process was followed. Verify it with plain code.
+
+**Try it in one command** — `npx runward init --example` scaffolds a filled reference mission and ends by running the strict gate itself: the whole chain goes green in front of you. The reference floor even ships an intentional failure (a value the model invented) that the deterministic guard refuses — `npm run demo` in `code/` shows the catch. When you want it on your own project, `npx runward init` starts a blank mission. MIT, zero key, zero network by default.
 
 > Spec Kit, OpenSpec and BMAD take you to tested, sometimes merged code. Runward pilots the whole mission — and picks up their output if you use them. What none of them *structures* is the run: governed memory, resilience, execution security, continuous evaluation, transmission.
 
+## Documentation
+
+The full documentation is at **[runward.dev/docs](https://runward.dev/docs)** — written for humans and coding agents alike, with a Markdown twin (`.md`) and a copy-to-clipboard button on every page.
+
+- **[Quickstart](https://runward.dev/docs/getting-started/quickstart/)** — from an empty directory to a green `runward check`.
+- **[Concepts: the deterministic gate](https://runward.dev/docs/concepts/the-gate/)** — what the gate verifies, and why it is deterministic and zero-LLM.
+- **[The six phases](https://runward.dev/docs/concepts/six-phases/)** — the gated delivery spine, phase by phase.
+- **[From an AI agent](https://runward.dev/docs/operating/from-an-agent/)** — how an agent installs and drives runward end to end.
+- **[Compliance evidence](https://runward.dev/docs/compliance/evidence/)** — framed for ISO 42001, NIST AI RMF and the EU AI Act, exported as OSCAL.
+- **[How it compares](https://runward.dev/docs/compare/)** — Spec Kit, BMAD, Kiro, OpenSpec, Spec Kitty: sourced, from their own docs.
+- **[Case study: dropyour](https://runward.dev/docs/case-study/)** — a real product shipped with runward, the trail gate by gate.
+
 ## Why
 
-Nearly everything that calls itself agentic today dies somewhere between the demo and production. Not because the model is weak, but because nobody can evaluate a non-deterministic behavior, govern it, or say in advance when it fails. These are architecture problems, not model problems. The industry's own signal is unambiguous: model vendors now deploy engineers directly into client organizations, because the bottleneck has moved from the model to its integration into the real world.
+Runward exists to carry an agentic system across the stretch where nearly everything dies today: between the demo and production. Not because the model is weak, but because nobody can evaluate a non-deterministic behavior, govern it, or say in advance when it fails. These are architecture problems, not model problems. The industry's own signal is unambiguous: model vendors now deploy engineers directly into client organizations, because the bottleneck has moved from the model to its integration into the real world.
 
-Spec-driven frameworks answered the first half of that problem: write the right thing. Nobody structured the second half: ship it, run it, hand it over. That is why Runward exists.
+Spec-driven frameworks answered the first half of that problem: write the right thing. Runward structures the second half: ship it, run it, hand it over.
 
 Agentic systems break four assumptions of classical distributed engineering. The core component is **non-deterministic**: same input, different output, by design. **Input is indistinguishable from instruction**: anything the model reads can try to command it, so prompt injection is structural, not a bug to patch. **Forgetting becomes an engineering problem**: memory that only grows drowns the signal, so decay, invalidation and consolidation have to be designed, not hoped for. And the **blast radius is unprecedented**: an agent with tools acts on the world, so a bad output is no longer just a bad answer.
 
-Runward is the **FDE method** made executable. Its guiding principle: the architecture frames the model, never the other way around — the model and the infrastructure are adapter decisions, taken behind stable contracts. From there, five architecture gestures: boundaries before the stack; start simple, isolate by contract, grow on evidence; keep the deterministic out of the model; explicit state and governed memory; govern, trace and evaluate from day zero. And a delivery spine: six gated phases (a gate: a checkpoint you cross on evidence, never on assertion), each with a Definition of Ready and a Definition of Done, a 22-arbitration decision matrix, and 64 craft rules. The phases, gestures and rules are what carry it.
+Runward is the **FDE (Forward Deployed Engineer) method** made executable — the way those embedded engineers deliver, written down and gated. Its guiding principle: the architecture frames the model, never the other way around — the model and the infrastructure are adapter decisions behind stable contracts. From there, a delivery spine: six gated phases (a gate: a checkpoint you cross on evidence, never on assertion), each with a Definition of Ready and a Definition of Done, a decision matrix, and 64 craft rules — the detail is in the sections below.
 
 ## Who it's for — and when
 
@@ -51,7 +65,7 @@ npx runward --yes init           # non-interactive, defaults (CI-friendly)
 npx runward init --tools claude,cursor,copilot,gemini,windsurf
 ```
 
-**Fastest way to see what runward does:** `npx runward init --example` scaffolds the `request-triage` reference mission already filled, so `runward check` passes green and `runward compliance iso-42001` emits an audit-ready OSCAL pack out of the box. Then `npx runward init` (no `--example`) starts your own mission from blank templates.
+**Fastest way to see what runward does:** `npx runward init --example` scaffolds the `request-triage` reference mission already filled and ends by running `check --strict` itself — every gate green, in one command. Then `cd code && npm install && npm run demo` runs five requests end to end; one of them (req-005) carries an account reference the model invented, and you watch the deterministic guard refuse to route on it, fail-closed. `runward compliance iso-42001` emits an audit-ready OSCAL pack from the traced decisions. When you're ready, `npx runward init` (no `--example`) starts your own mission from blank templates.
 
 **Install the gate where you already work — honestly tiered by how hard it blocks:**
 
@@ -138,14 +152,14 @@ Four things, and a code-level competitive check (July 2026) confirmed no other s
 - **The gate you own — deterministic and zero-LLM.** `runward check --strict` is a non-probabilistic, operator-owned exit-code gate: it cannot be jailbroken by injection (no model in the gate path) and reruns byte-for-byte. Every competitor's *code* check is judged by the model; this one does not depend on an LLM to pass. (Two 2026 signals back the stance: FedRAMP RFC-0024 forbids GenAI-produced factual evidence, and the Delve affair showed why AI-produced audit evidence is not trusted.)
 - **The gate verifies the evidence, not just the row.** A pointer must resolve to real, non-empty content; a symbol or test name must actually be there; a rule can declare the shape its evidence must contain (`signature:` — the founding cited-not-applied incident is now caught deterministically); a stale pointer fails the gate; a sealed gate (`--freeze`) makes later erosion loud. Still bytes, never judgment — and never a model.
 - **runward gates itself.** This repository carries its own `runward/` mission, and CI requires `runward check --strict` green on runward's own code — including under network isolation. The discipline is demonstrated, not claimed.
-- **Audit-ready evidence, in a published format.** Craft rules carry an OWASP ASI (Top 10 for Agentic Applications) mapping — a universal, region-agnostic security posture — so the conformance manifest reads as supporting evidence and exports as a machine-readable OSCAL pack. The decision → ADR → manifest → OSCAL chain is a **versioned, citable mini-spec** ([`docs/spec/runward-oscal-mapping.md`](docs/spec/runward-oscal-mapping.md)) anyone can reproduce or critique — the reference implementation of gate-level agentic-delivery evidence, not a black box. Security-only by default; it maps to your regime when you need one — ISO/IEC 42001 (global), NIST AI RMF (US), or the EU AI Act art. 13 technical file (EU) — see [`docs/compliance/`](docs/compliance/). An input to that work — never a conformity assessment, never a claim to certify.
+- **Audit-ready evidence, in a published format.** Craft rules carry an OWASP ASI (Top 10 for Agentic Applications) mapping — a universal, region-agnostic security posture — so the conformance manifest reads as supporting evidence and exports as a machine-readable OSCAL pack. The decision → ADR → manifest → OSCAL chain is a **versioned, citable mini-spec** ([`docs/spec/runward-oscal-mapping.md`](docs/spec/runward-oscal-mapping.md)) anyone can reproduce or critique — the reference implementation of gate-level agentic-delivery evidence, not a black box. Security-only by default; it maps to your regime when you need one — ISO/IEC 42001 (global), NIST AI RMF (US), or the EU AI Act technical documentation (art. 11 / Annex IV) (EU) — see [`docs/compliance/`](docs/compliance/). An input to that work — never a conformity assessment, never a claim to certify. For a regulated procurement / TPRM review — what applies, what is moot because runward is **local with no data flow**, the supply-chain evidence (OIDC provenance + an attested CycloneDX **SBOM** on every release), the OpenSSF OSPS Baseline alignment, the licence framing and the honest limits — see [`docs/compliance/regulated-adoption.md`](docs/compliance/regulated-adoption.md) ([ADR-0031](docs/adr/ADR-0031-sovereign-engineering-evidence-for-regulated-environments.md)).
 - **Never a runtime.** Runward writes nothing into `.git/`, installs nothing, and runs nothing of yours — it frames, gates and hands off. Your runtime and model are swappable adapters behind a port; the thing you depend on is never Runward.
 - **Floor, not MVP deck.** The floor is the smallest *running* system that proves value on real traffic. A presentation is not a floor.
 - **Evolution on evidence.** Multi-agent, long-term memory, microservices, a bigger model: each has a sober default and an explicit trigger. No trigger, no complexity. Every switch is an ADR.
 - **Security by architecture, not detection.** Prompt injection is constrained structurally (lethal trifecta, 2-of-3 rule), not filtered heuristically.
 - **Craft rules, not vibes.** 64 engineering craft rules ship with the mission (memory scoring, tiered retrieval, event sourcing, request-id propagation, multi-provider fallback, cost routing, post-turn pipelines, prompt-injection defenses…) — your agent applies them, `runward check` will not invent them. Code examples follow the reference-stack default (a single language in the core — TypeScript by default, an adapter decision like any other: see the decision matrix). The patterns are the contract; the language is the adapter.
 - **One accountable operator, not a simulated team.** One human owns every gate while the agent executes the workflows — see [the operator role](docs/operator-role.md).
-- **Hand-over gated on proof, not a folder.** The mission ends when the receiving team redoes a real task without you — and that succession is a gated deliverable (`handover.md`, four handover rules), verified like every other phase. No other scaffold carries the mission past tested code, let alone checks the succession.
+- **Hand-over gated on proof, not a folder.** The mission ends when the receiving team redoes a real task without you — and that succession is a gated deliverable (`handover.md`, four handover rules), verified like every other phase. Only one other scaffold (Spec Kitty) carries the mission past tested code — and its acceptance verdict is an AI review; runward's succession check is plain code, and its evidence exports as standardized OSCAL, not bespoke YAML.
 
 ## The reference floor
 

package/dist/commands/init.js

@@ -4,6 +4,7 @@ import { checkbox, input, select } from "@inquirer/prompts";
 import { TEMPLATES, EXAMPLE_MISSION, EXAMPLE_CODE, MISSION_LAYOUT, VERSION } from "../lib/paths.js";
 import { TOOL_PROFILES, TOOL_IDS, baselineSkills } from "../lib/tools.js";
 import { makeWriter } from "../lib/write.js";
+import { checkCommand } from "./check.js";
 import { c, createHeader, isNonInteractive, section, status } from "../lib/styles.js";
 /** Recursively copy a shipped directory tree (used to lay down the filled reference mission). */
 const COPY_SKIP = new Set(["node_modules", "package-lock.json", ".DS_Store"]);
@@ -130,12 +131,18 @@ export async function initCommand(opts) {
     console.log(status.success(`${w.stats.written} file(s) ${dryRun ? "planned" : "written"}, ${w.stats.skipped} skipped`));
     if (example) {
         console.log(`
-${c.primaryBold("Filled reference mission — the whole chain is already green.")}
-  1. Run ${c.primary("runward check")} — every gate passes; the deliverables are filled, not blank.
+${c.primaryBold("Filled reference mission — the gate audit runs on it right below.")}
+  1. See the deterministic guard refuse a fabricated value: ${c.primary("cd code && npm install && npm run demo")} ${c.gray("(req-005 carries an account reference the model invented — refused, fail-closed).")}
   2. Run ${c.primary("runward compliance iso-42001")} — an audit-ready evidence pack (OSCAL) derived from the traced decisions.
   3. Read ${c.white("runward/framing.md")}, the ADRs in ${c.white("runward/adr/")}, and ${c.white("runward/governance/threat-model.md")} to see how a real mission is traced end to end.
 
 ${c.gray("Start your own mission with")} ${c.primary("runward init")} ${c.gray("(without --example) to get blank templates.")}`);
+        // One command, whole chain: the scaffold ends by auditing itself, so the first
+        // contact with runward is the strict gate going green — not a promise to run it later.
+        if (!dryRun) {
+            console.log();
+            await checkCommand({ path: dir, strict: true });
+        }
     }
     else {
         console.log(`

package/dist/lib/compliance.js

@@ -314,7 +314,7 @@ function detUuid(seed) {
     const s = b.join("");
     return `${s.slice(0, 8)}-${s.slice(8, 12)}-${s.slice(12, 16)}-${s.slice(16, 20)}-${s.slice(20, 32)}`;
 }
-const OSCAL_VERSION = "1.1.2";
+const OSCAL_VERSION = "1.2.2";
 const ASI_CATALOG = "https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/";
 /**
  * Render the OWASP ASI control coverage as an OSCAL component-definition (JSON) — regime-neutral, the

package/dist/lib/evidence.js

@@ -55,11 +55,15 @@ function clean(token) {
 }
 /**
  * A rule signature is operator-authored data the gate compiles into a RegExp and runs against file
- * content — so a catastrophic-backtracking pattern (nested quantifiers like `(a+)+`) could hang the
- * gate on adversarial input (a self-inflicted DoS in CI). Reject the known-dangerous shape up front,
- * deterministically: a quantifier applied to a group that itself contains a quantifier. This is a
- * conservative screen (it may reject a rare safe pattern — the operator rewrites it), never a promise
- * to catch every pathological regex. Signatures are simple token alternations in practice. See ADR-0020.
+ * content — so a catastrophic-backtracking pattern could hang the gate on adversarial input (a
+ * self-inflicted DoS in CI). Reject the two known-dangerous shapes up front, deterministically:
+ *   1. a quantifier applied to a group that itself contains a quantifier — `(a+)+`, `([a-z]+)*`;
+ *   2. a quantifier applied to a group holding an alternation — `(a|a)+`, `(ab|a)+`, `(\d|\d)*` —
+ *      whose branches can overlap and blow up (the class the shape-1 screen misses).
+ * This is a conservative screen (it may reject a rare safe pattern like `(a|b)+` — the operator
+ * rewrites it), never a promise to catch every pathological regex; a linear-time engine (RE2) would
+ * be the complete fix, at the cost of a native dependency this zero-dep core avoids. Signatures are
+ * simple token alternations in practice. See ADR-0020.
  */
 export function unsafeSignature(source) {
     // Normalize character classes ([...], including [^()]) to a single token first: a quantifier INSIDE
@@ -67,9 +71,11 @@ export function unsafeSignature(source) {
     // own `[^()]` stops at the `(` that lives literally inside the class. After normalization the class
     // becomes `C`, so `([^()]+)+` reads as `(C+)+` and is caught.
     const norm = source.replace(/\[(?:\\.|[^\]\\])*\]/g, "C");
-    // group whose body holds a quantifier, immediately followed by another quantifier: (…+…)+ (…*…)* etc.
+    // 1. group whose body holds a quantifier, immediately followed by another quantifier: (…+…)+ (…*…)* etc.
     const NESTED = /\((?![?])[^()]*[+*}][^()]*\)[+*{]/;
-    return NESTED.test(norm) || NESTED.test(source);
+    // 2. group holding an alternation, immediately followed by a quantifier: (…|…)+ (…|…)* etc.
+    const ALT = /\((?![?])[^()]*\|[^()]*\)[+*{]/;
+    return NESTED.test(norm) || NESTED.test(source) || ALT.test(norm) || ALT.test(source);
 }
 /** The same three resolution bases as the drift pass (ADR-0004). */
 export function resolutionBases(missionDir, deliverable) {
@@ -163,7 +169,7 @@ export function evidenceReport(missionDir, deliverable, signatures) {
         const sig = signatures[row.rule];
         if (sig) {
             if (unsafeSignature(sig)) {
-                out.push({ rule: row.rule, problem: `unsafe signature regex (nested quantifiers risk catastrophic backtracking): /${sig}/ — simplify it in runward/rules/${row.rule}.md` });
+                out.push({ rule: row.rule, problem: `unsafe signature regex (nested or overlapping-alternation quantifiers risk catastrophic backtracking): /${sig}/ — simplify it in runward/rules/${row.rule}.md` });
                 continue;
             }
             let re;

package/dist/lib/tools.js

@@ -64,7 +64,7 @@ const skillMd = (s) => [
     "",
     skillBody(s),
 ].join("\n");
-/** Emit the four phase skills as SKILL.md folders under `<root>/<...dir>/runward-<phase>/SKILL.md`. */
+/** Emit the five phase skills as SKILL.md folders under `<root>/<...dir>/runward-<phase>/SKILL.md`. */
 const skillsAt = (root, ...dir) => PHASE_SKILLS.map((s) => ({ path: join(root, ...dir, `runward-${s.phase}`, "SKILL.md"), content: skillMd(s) }));
 /**
  * The vendor-neutral phase skills at `.agents/skills/` — the converged SKILL.md alias read by

package/examples/request-triage/code/README.md

@@ -41,7 +41,7 @@ Prerequisite: Node 20+.
 ```bash
 npm install
 npm test     # 14 deterministic tests via node:test + tsx
-npm run demo # four requests end to end, including a compliance suspension
+npm run demo # five requests end to end, including a compliance suspension and a fabricated account the guard refuses
 ```
 
 ## Layout

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "runward",
-  "version": "0.19.0",
-  "description": "After the spec: ship and run. A delivery framework for agentic systems \u2014 floor first, evolution on evidence, governance from day zero, handover with proof.",
+  "version": "0.21.0",
+  "description": "After the spec: ship and run. A delivery framework for agentic systems — floor first, evolution on evidence, governance from day zero, handover with proof.",
   "keywords": [
     "agentic",
     "ai-agents",
@@ -44,7 +44,7 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22.12.0"
   },
   "scripts": {
     "build": "tsc",

package/regimes/eu-ai-act@2024-1689.json

@@ -3,6 +3,7 @@
   "regime": "eu-ai-act",
   "label": "EU AI Act (Annex IV)",
   "version": "2024-1689",
+  "reviewBy": "2026-08-02",
   "notes": "Mapped against Regulation (EU) 2024/1689 (OJ L, 12 July 2024), as amended by the Digital Omnibus on AI (Council final green light 29 June 2026), which postponed the Annex III high-risk obligations to 2 December 2027 (Annex I to 2 August 2028). The 2 August 2026 milestone remains real for other obligations (Article 50 transparency for systems placed on the market after that date, governance, GPAI enforcement) but is NOT the high-risk / Annex IV deadline. Annex IV wording moves — confirm against the Official Journal before filing.",
   "highRisk": {
     "bindFrom": "2 December 2027",

package/regimes/iso-42001@2023.json

@@ -3,6 +3,7 @@
   "regime": "iso-42001",
   "label": "ISO/IEC 42001",
   "version": "2023",
+  "reviewBy": "2027-01-01",
   "notes": "Mapped 2026-07 against ISO/IEC 42001:2023 (first edition, 2023-12). ISO Annex A control counts/templates are behind the paywalled standard — confirm against the purchased text.",
   "clauses": {
     "riskAssessment": "6.1.2",

package/regimes/nist-ai-rmf@1.0.json

@@ -3,6 +3,7 @@
   "regime": "nist-ai-rmf",
   "label": "NIST AI RMF",
   "version": "1.0",
+  "reviewBy": "2027-01-01",
   "notes": "Mapped 2026-07 against NIST AI 100-1 (AI RMF 1.0, January 2023) and the companion Playbook.",
   "crosswalk": {
     "primary": "each agentic-security risk lands primarily under **MEASURE** (test & evaluate, esp. security & resilience) and **MANAGE** (risk treatment)",