runward 0.12.1 → 0.12.2

package/NOTICE.md

@@ -6,7 +6,7 @@ The doctrine **“Designing and Running Agentic Systems”** (Thibault Souris, 2
 
 What this means in practice:
 
-- The **ideas and methods** (the six-phase method, the LLM Boundary Principle, floor-first delivery, evolution on triggers, lethal trifecta rule…) are free by nature. This repository implements them; you can too.
+- The **ideas and methods** (the six-phase method, the architecture that frames the model, floor-first delivery, evolution on triggers, lethal trifecta rule…) are free by nature. This repository implements them; you can too.
 - The **expression** of the doctrine (its text, figures, layout) is protected: you may share the published PDFs unmodified, you may not create derivative versions of the text.
 - Workflows and templates in this repository are original MIT-licensed writings that implement the method. They are the contribution surface.
 

package/README.md

@@ -22,7 +22,7 @@ Spec-driven frameworks answered the first half of that problem: write the right
 
 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's answer opens with a founding inversion — the **LLM Boundary Principle**: the architecture constrains the model, never the other way around. That opening posture unfolds into five 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. The full base is the method itself: 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 54 craft rules. The inversion opens the method; the phases, gestures and rules are what carry it.
+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 60 craft rules. The phases, gestures and rules are what carry it.
 
 ## Who it's for — and when
 
@@ -83,7 +83,7 @@ your-project/
 │   ├── shared-bricks.md         # bricks beyond the app: placement families, brick matrix, sovereignty by data class
 │   ├── floor.md                 # the smallest system that proves value on real traffic
 │   ├── adr/                     # one ADR per structural decision, with re-evaluation trigger
-│   ├── rules/                   # 54 craft rules your agent applies while building
+│   ├── rules/                   # 60 craft rules your agent applies while building
 │   ├── governance/
 │   │   ├── threat-model.md      # lethal trifecta, 2-of-3 rule on the context window
 │   │   ├── evaluation-rubric.md # test the deterministic, evaluate the non-deterministic
@@ -118,7 +118,7 @@ Phase 5 is transverse: it starts at day zero, not after the incident.
 - **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.** 54 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.
+- **Craft rules, not vibes.** 58 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).
 - **Handover as a deliverable.** The mission ends when the receiving team is autonomous, with proof.
 

package/dist/cli.js

@@ -87,7 +87,7 @@ program
 program
     .command("compliance")
     .description("assemble a regime-framed evidence pack from the mission (deterministic, read-only; a readiness draft, never a compliance claim)")
-    .argument("[regime]", "iso-42001 (nist-ai-rmf / eu-ai-act: coming)")
+    .argument("[regime]", "iso-42001 | nist-ai-rmf | eu-ai-act")
     .option("-p, --path <path>", "project directory")
     .action(complianceCommand);
 program.parseAsync();

package/dist/commands/compliance.js

@@ -25,11 +25,6 @@ export async function complianceCommand(regime, opts) {
         process.exit(2);
     }
     const spec = REGIMES[key];
-    if (!spec.render) {
-        console.error(status.error(`The ${spec.label} lens is not assembled yet — only iso-42001 for now (ADR-0016, built piece by piece).`));
-        console.log("  " + c.darkGray(`See the framing reference: docs/compliance/${key}.md`));
-        process.exit(2);
-    }
     const root = findMissionRoot(resolve(process.cwd(), opts.path ?? "."));
     if (!root) {
         console.error(status.error("No runward/ mission found here or above. Run `runward init` first."));

package/dist/lib/compliance.js

@@ -54,6 +54,7 @@ function readRules(missionDir) {
 /** The three build-phase deliverables that carry a `## Rule conformance` manifest (as `check --strict`). */
 const CONFORMANCE_DELIVERABLES = [
     ["Architect", "architecture.md"],
+    ["Topology", "execution-topology.md"],
     ["Floor", "floor.md"],
     ["Govern", "governance/threat-model.md"],
 ];

package/dist/lib/constants.js

@@ -1,8 +1,8 @@
 /** Total number of craft rules shipped under templates/rules/. */
-export const EXPECTED_RULES = 58;
+export const EXPECTED_RULES = 60;
 /** Gate adapters shipped under templates/adapters/ (ADR-0012): one per harness seam, plus the port-contract README. */
 export const EXPECTED_ADAPTERS = 4;
 /** Routed-count floor: minimum CRITICAL/HIGH rules mapped to each build phase (ADR-0002).
  *  Lowering a floor is a deliberate, tracked edit — the `phases:` mapping cannot be silently
  *  stripped to make `check --strict` pass vacuously. */
-export const EXPECTED_MAPPED = { architect: 6, topology: 4, floor: 10, govern: 10 };
+export const EXPECTED_MAPPED = { architect: 6, topology: 4, floor: 10, govern: 12 };

package/dist/lib/rule-migrations.js

@@ -1,7 +1,7 @@
 export const RULE_MIGRATIONS = {
     "hexa-llm-boundary-principle": {
         to: "hexa-move-deterministic-out",
-        reason: "the name is reserved for the founding inversion",
+        reason: "renamed to name the pattern directly (move the deterministic out of the model)",
         since: "v0.7.0",
     },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runward",
-  "version": "0.12.1",
+  "version": "0.12.2",
   "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",

package/templates/rules/frontier-deterministic-boundary.md

@@ -12,7 +12,7 @@ tags: [architecture, llm, frontier, grounding, safety, determinism]
 > **The model writes prose. The program owns the facts.**
 > Anything that can be retrieved, computed, validated or decided deterministically must live in code, never in the model's free generation. The model is rented and non-deterministic; the boundary around it is owned and tested.
 
-This is the strongest form of the LLM Boundary Principle: not only move deterministic *logic* out (routing, classification), but move deterministic *truth* out. The model is allowed to phrase, summarise and connect. It is never the source of a number, a citation, a price, a date, or an authorisation.
+This is the strongest form of that boundary: not only move deterministic *logic* out (routing, classification), but move deterministic *truth* out. The model is allowed to phrase, summarise and connect. It is never the source of a number, a citation, a price, a date, or an authorisation.
 
 **Why structured outputs are not enough:** constrained decoding and JSON schema guarantee the *shape* of the output, never its *meaning*. A model can emit a perfectly valid JSON number that is invented. Shape validation and truth validation are two different jobs.
 

package/templates/rules/hexa-move-deterministic-out.md

@@ -7,7 +7,7 @@ impactDescription: Reduces LLM costs and latency by moving deterministic logic o
 tags: [architecture, llm, cost-optimization, performance]
 ---
 
-## LLM Boundary Principle
+## Move the Deterministic out of the Model
 
 > **Everything that can be deterministic, testable, and cacheable must be moved out of the LLM.**
 

package/templates/rules/security-code-execution-sandbox.md

@@ -0,0 +1,20 @@
+---
+title: Unexpected Code Execution Runs Sandboxed, Never In-Process
+impact: CRITICAL
+asi: [ASI05, ASI02]
+phases: [govern]
+impactDescription: Caps the blast radius of any code the agent runs (generated or tool-provided) by isolating it from the host, secrets and network
+tags: [security, code-execution, sandbox, isolation]
+---
+
+## Unexpected Code Execution Runs Sandboxed, Never In-Process
+
+> **Code the model produced, or a tool ran, is untrusted input that acts.** It executes in an isolated, least-privilege sandbox, never in the agent's own process.
+
+Any path where a model output becomes execution — a code interpreter, a shell tool, an `eval`, a generated script, a plugin that runs code — is treated as **unexpected code execution** and confined:
+
+- **Isolation, not trust.** The code runs in a sandbox with no access to the host filesystem, the agent's process memory, the network, or secrets, unless a capability was explicitly and narrowly granted. Generated code never inherits the agent's privileges.
+- **An explicit, approved capability, never an implicit tool.** "Run arbitrary code" is not a default tool the model may call at will; it is a declared, approval-gated capability with a bounded scope (allowed language, timeout, resource ceiling, allowed paths and syscalls).
+- **No path from untrusted content to execution.** Retrieved or user-supplied content must not reach a code-execution surface without the deterministic guard and human approval on the action (see `security-prompt-injection`, the 2-of-3 rule).
+
+Form validation is not enough: a model can emit syntactically valid code that deletes data or exfiltrates a secret. The boundary around execution is owned and tested, not hoped.

package/templates/rules/security-human-agent-trust.md

@@ -0,0 +1,20 @@
+---
+title: Provenance on Every Field, So the Human Never Trusts a Guess
+impact: HIGH
+asi: [ASI09]
+phases: [govern]
+impactDescription: Stops a model-proposed value being read as a verified fact at the approval point — the human decides on real provenance, never on fabricated confidence
+tags: [security, trust, provenance, human-oversight]
+---
+
+## Provenance on Every Field, So the Human Never Trusts a Guess
+
+> **The model writes the prose; the program owns the facts — and the human must be able to tell which is which.** A model-proposed value is never presented as verified.
+
+Human-agent trust breaks when a person approves an action believing the agent's output was checked, when it was only proposed. The guard is provenance made visible, and approval placed on the action:
+
+- **Every field carries a provenance marker** — `computed`, `verified`, or `model-proposed` — so the human, and the code, can tell a fact the program owns from a value the model guessed. A `model-proposed` value that would act on the world is refused fail-closed until it is verified or approved (see `frontier-deterministic-boundary`, `data-memory-provenance`).
+- **Approval is on the action, shown with its provenance**, never on a wall of confident prose. The human sees what is proposed versus verified before deciding, so a sign-off is a real decision, not a reflex.
+- **The agent never impersonates a human or an authority.** It is an identified principal, distinct from the user it serves; its outputs are attributable to the agent, and it never claims a certainty, a sign-off, or an identity it does not have.
+
+Confident tone is not correctness. The system makes the difference legible, so the human's trust is placed on evidence, not on fluency.

package/templates/workflows/architect.md

@@ -19,11 +19,11 @@ Use this workflow once framing is decided and structure must follow: "how do we
 
 ## 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.
+**Refuse stack questions, again.** Contracts first, technology later. The phase rests on the doctrine's guiding 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.
+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 guiding principle 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.

package/templates/workflows/method.md

@@ -12,7 +12,7 @@ Use this workflow whenever an agentic-system mission needs to be planned, advanc
 
 ## 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).
+**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 principle underneath — 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.