runward 0.12.1 → 0.13.0

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
 
@@ -45,11 +45,14 @@ The cost is discipline: one accountable operator, governance from day zero, and
 ## Install
 
 ```bash
-npx runward init                 # interactive wizard
+npx runward init --example       # a filled reference mission — see the whole chain green in one command
+npx runward init                 # interactive wizard (blank templates for your own mission)
 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.
+
 New here? Follow [your first mission in 15 minutes](docs/first-mission.md).
 
 ### Commands
@@ -83,7 +86,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 +121,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

@@ -54,6 +54,7 @@ program
     .option("-p, --path <path>", "project directory (default: prompt, or . with --yes)")
     .option("-t, --tools <list>", "comma-separated tool profiles: claude,cursor,copilot,gemini,windsurf")
     .option("--force", "overwrite existing files")
+    .option("--example", "scaffold a filled reference mission (request-triage) — the whole chain is green out of the box")
     .action(initCommand);
 program
     .command("check")
@@ -87,7 +88,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/commands/init.js

@@ -1,19 +1,32 @@
 import { join, resolve } from "node:path";
 import { readdirSync } from "node:fs";
 import { checkbox, input, select } from "@inquirer/prompts";
-import { TEMPLATES, MISSION_LAYOUT, VERSION } from "../lib/paths.js";
+import { TEMPLATES, EXAMPLE_MISSION, MISSION_LAYOUT, VERSION } from "../lib/paths.js";
 import { TOOL_PROFILES, TOOL_IDS } from "../lib/tools.js";
 import { makeWriter } from "../lib/write.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). */
+function copyTree(w, srcDir, destDir) {
+    for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
+        const src = join(srcDir, entry.name);
+        const dest = join(destDir, entry.name);
+        if (entry.isDirectory())
+            copyTree(w, src, dest);
+        else
+            w.copy(src, dest);
+    }
+}
 export async function initCommand(opts) {
     console.log(createHeader(`Runward v${VERSION}`, "After the spec: ship and run"));
     const yes = isNonInteractive();
+    const example = opts.example ?? false;
     const dryRun = process.env.RUNWARD_DRY_RUN === "1";
     // ── Gather answers (wizard, or defaults with --yes) ──────────────
     const dir = opts.path
         ?? (yes ? "." : await input({ message: "Project directory", default: "." }));
     // The idea seeds the framing note: you arrive with a project, not with paperwork.
-    const idea = yes ? "" : await input({
+    // In example mode the framing is already filled from the reference, so we skip it.
+    const idea = (yes || example) ? "" : await input({
         message: "What are you building? (one line — it seeds your framing note)",
         default: "",
     });
@@ -25,14 +38,14 @@ export async function initCommand(opts) {
                 message: "Tool profiles (AGENTS.md is always written)",
                 choices: TOOL_PROFILES.map((t) => ({ value: t.id, name: t.label, checked: t.id === "claude" })),
             });
-    const entryMode = yes ? "greenfield" : await select({
+    const entryMode = (yes || example) ? "greenfield" : await select({
         message: "Entry mode",
         choices: [
             { value: "greenfield", name: "Greenfield — new system, run the chain from the top" },
             { value: "brownfield", name: "Brownfield — existing system, characterize before touching" },
         ],
     });
-    const tier = yes ? "floor" : await select({
+    const tier = (yes || example) ? "floor" : await select({
         message: "Stopping tier (the sponsor's choice — can be revised)",
         choices: [
             { value: "framing", name: "Framing only" },
@@ -47,20 +60,30 @@ export async function initCommand(opts) {
     const root = resolve(process.cwd(), dir);
     const mission = join(root, "runward");
     const w = makeWriter({ force: opts.force ?? false, dryRun, root });
-    console.log(section("Mission structure"));
-    const prefill = (s) => {
-        let out = s
-            .replace("[greenfield | brownfield M1–M4]", entryMode)
-            .replace("[framing | floor | full chain]", tier);
-        if (idea) {
-            out = out
-                .replace("[system or mission name]", idea)
-                .replace("## 1. Problem\n", `## 1. Problem\n\n> Seed idea (from init): "${idea}" — now replace this with the process as actually observed.\n`);
+    console.log(section(example ? "Mission structure (filled reference)" : "Mission structure"));
+    if (example) {
+        // Lay down the filled request-triage reference: every gate is green out of the box.
+        copyTree(w, EXAMPLE_MISSION, mission);
+        // The reference omits the three non-gated scaffolding notes; add them as blank templates so the scaffold stays complete.
+        for (const extra of ["reference-stack.md", "shared-bricks.md", "gap-analysis.md"]) {
+            w.copy(join(TEMPLATES, "mission", extra), join(mission, extra));
+        }
+    }
+    else {
+        const prefill = (s) => {
+            let out = s
+                .replace("[greenfield | brownfield M1–M4]", entryMode)
+                .replace("[framing | floor | full chain]", tier);
+            if (idea) {
+                out = out
+                    .replace("[system or mission name]", idea)
+                    .replace("## 1. Problem\n", `## 1. Problem\n\n> Seed idea (from init): "${idea}" — now replace this with the process as actually observed.\n`);
+            }
+            return out;
+        };
+        for (const [src, dest] of Object.entries(MISSION_LAYOUT)) {
+            w.copy(join(TEMPLATES, "mission", src), join(mission, dest), src === "framing.md" ? prefill : undefined);
         }
-        return out;
-    };
-    for (const [src, dest] of Object.entries(MISSION_LAYOUT)) {
-        w.copy(join(TEMPLATES, "mission", src), join(mission, dest), src === "framing.md" ? prefill : undefined);
     }
     console.log(section("Workflows"));
     for (const wf of readdirSync(join(TEMPLATES, "workflows"))) {
@@ -85,10 +108,21 @@ export async function initCommand(opts) {
     // ── Summary ───────────────────────────────────────────────────────
     console.log(section("Done"));
     console.log(status.success(`${w.stats.written} file(s) ${dryRun ? "planned" : "written"}, ${w.stats.skipped} skipped`));
-    console.log(`
+    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.
+  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.")}`);
+    }
+    else {
+        console.log(`
 ${c.primaryBold("Next steps")}
   1. Fill ${c.white("runward/framing.md")} — do not architect before the framing gate passes.
   2. Point your agent at ${c.white("AGENTS.md")} and ${c.white("runward/workflows/method.md")}.
   3. Run ${c.primary("runward check")} anytime to see which gate you are at.
 ${entryMode === "brownfield" ? c.warning("\n  Brownfield entry: start with runward/workflows/brownfield.md — characterize before touching.\n") : ""}`);
+    }
 }

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/paths.js

@@ -5,6 +5,8 @@ const HERE = dirname(fileURLToPath(import.meta.url));
 /** Package root (works from dist/lib/ at runtime). */
 export const PKG_ROOT = join(HERE, "..", "..");
 export const TEMPLATES = join(PKG_ROOT, "templates");
+/** Filled reference mission (shipped) — used by `init --example`. */
+export const EXAMPLE_MISSION = join(PKG_ROOT, "examples", "request-triage", "runward");
 export const VERSION = JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf8")).version;
 /** Mission layout: template file -> destination inside runward/ */
 export const MISSION_LAYOUT = {

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/examples/request-triage/README.md

@@ -0,0 +1,34 @@
+# Example mission: request triage
+
+A complete Runward mission, filled end to end, on a deliberately ordinary case: an organization receives heterogeneous inbound requests (support, sales, compliance) and triages them by hand. The floor is a qualifier that classifies each request, extracts the key fields, and routes it — with an observable success criterion measured on real traffic against the manual baseline.
+
+Every document follows the corresponding template in `templates/mission/`, placeholders replaced. All names, volumes and figures are **illustrative**: they show what a filled note looks like, not a real engagement.
+
+## How to read it
+
+Read in mission order — the order the workflows produce them:
+
+1. `runward/framing.md` — the problem, the observable success criterion, floor vs target, named deferrals, DoR check (one condition carried as a named risk).
+2. `runward/mission-contract.md` — the one-page steering contract signed with the sponsor: engagements, DoD, gates.
+3. `runward/architecture.md` — boundaries before stack: ports, versioned contract, default topology with triggers, language explicitly left open.
+4. `runward/decision-matrix.md` — the arbitration reference, adopted at the Architect gate; every position on its sober default.
+5. `runward/contracts/` — the four port contracts the architecture note declares: request intake, model, routing, persistence.
+6. `runward/adr/ADR-0001-single-orchestrator.md` — the sober default, with its dated reevaluation trigger.
+7. `runward/adr/ADR-0002-deterministic-guard-on-extracted-fields.md` — the model never supplies a value the system can compute or verify deterministically.
+8. `runward/governance/` — instrumented from day zero, not retrofitted: threat model (the 2-of-3 rule held by construction), evaluation rubric (floor-tier capabilities: routing fidelity, abstention, criterion compliance — no memory bench, because the floor has no memory), observability schema.
+9. `runward/floor.md` — the proof record: what shipped, what was measured, gaps, and which trigger is watched next.
+10. `runward/runbook.md` — what the receiving team inherits: startup, degraded modes, recovery, failover.
+
+The chain passes the gate audit: `runward check -p examples/request-triage` exits 0 (the smoke test asserts it).
+
+Notice what the documents *refuse* to do: no stack picked at framing, no complexity without a trigger, no proof on hand-picked cases, no evaluation of capabilities the floor does not have.
+
+## Runnable floor
+
+The mission is also executable: [`code/`](code/) contains a standalone
+TypeScript package (no key, no network, deterministic model adapter) that
+implements what the documents decide — closed-vocabulary classification,
+the deterministic guard on extracted fields (ADR-0002), guarded routing,
+fail-closed compliance through suspend-and-rehydrate, abstention on unknown.
+`npm install && npm test` in `code/` runs its 14 deterministic tests; see
+[`code/README.md`](code/README.md).

package/examples/request-triage/runward/adr/ADR-0001-single-orchestrator.md

@@ -0,0 +1,37 @@
+# ADR-0001: single orchestrator, sequential triage
+
+**Date**: 2026-05-12
+**Status**: accepted
+**Deciders**: operator, Head of Operations (sponsor)
+**Method**: decision-loop: reality-check on the observed process, sourced state of the art, challenge, durable position
+
+## Context
+
+Triaging one request is a short sequence of dependent steps: normalize the raw input, propose a classification and field extractions (model), validate or recompute the extracted fields (deterministic, see ADR-0002), resolve the target queue, route or escalate to human review, persist. Each step consumes the output of the previous one; none is independent enough to parallelize, none handles content requiring an isolated context. Volume is ~400 requests per week — throughput is not a force here. The decision is taken at the orchestration boundary, behind the primary RequestIntakePort; it is structuring because topology is expensive to unwind once adapters and observability are built around it.
+
+## Decision
+
+One orchestrator, running a fixed sequential plan per request, holding no instance state. It composes the steps and carries no business logic: classification rules live in the domain, validation in the guards, translation in the adapters. This applies the framework's sober default: no multi-agent until a genuinely parallelizable or isolation-requiring subtask exists.
+
+## Alternatives discarded
+
+- **Multi-agent (one agent per step)**: discarded. No step is isolable enough to deserve its own context; the coordination and token overhead buys nothing measurable at this volume.
+- **Model-driven dynamic planning**: discarded. The triage sequence is known and stable; letting the model decide the plan adds non-determinism, cost, and an attack surface without adding value.
+- **Event-driven pipeline (queue between each step)**: tempered rather than eliminated. Useful at scale for backpressure, but at 400 requests/week it multiplies moving parts for no observed load. The persistence log already gives replayability.
+
+## Consequences
+
+- **Positive**: deterministic, replayable trajectories; a single point of cost accounting and tracing; one request ID covers the whole run with no parent-child lineage to manage; the fixed plan keeps model spend to the two calls that need it.
+- **Negative, accepted**: if one step becomes heavy and independent — for example untrusted attachment processing that should run quarantined — the topology must be revisited. Cost taken on knowingly.
+- **On other boundaries**: observability stays flat (one trajectory per request); security review has one path to guard; the contract between steps is internal and free to change until a step crosses a process boundary.
+
+## Reevaluation trigger (mandatory, dated)
+
+Reopen this decision when either observable signal appears: (1) a subtask requiring an isolated context or genuine parallelism enters scope — the named candidate is attachment processing, currently out of scope; or (2) end-to-end triage latency exceeds 60 seconds at p95 over a full week, measured on the observability schema, indicating the sequential plan no longer holds the load. Until then, apply without reopening.
+
+**Trigger set on**: 2026-05-12 · **Watched via**: weekly review of the p95 latency metric and the scope backlog
+
+## References
+
+- [architecture.md](../architecture.md) §4 — default topology and triggers.
+- [ADR-0002](ADR-0002-deterministic-guard-on-extracted-fields.md) — the guard step this plan sequences.

package/examples/request-triage/runward/adr/ADR-0002-deterministic-guard-on-extracted-fields.md

@@ -0,0 +1,38 @@
+# ADR-0002: deterministic guard on model-extracted fields
+
+**Date**: 2026-05-12
+**Status**: accepted
+**Deciders**: operator, Head of Operations (sponsor)
+**Method**: decision-loop: reality-check on the TriageRecord contract, challenge on failure modes, durable position
+
+## Context
+
+The model proposes the classification and the extracted key fields (requester identity, account reference, stated deadline). Those fields drive an action: routing into the ticketing system, where a wrong account reference attaches the request to the wrong customer and a missed deadline flag can breach a regulatory response window. A model-proposed value is a hypothesis, not a fact — plausible-looking account references and dates are exactly what a language model fabricates most fluently. The framing note's attached condition (no silent miss on compliance requests) makes this the highest-stakes boundary in the system. The decision is taken at the domain's output boundary, between the model port and the routing port.
+
+## Decision
+
+Every model-extracted field is validated or recomputed deterministically before any action is taken on it. **The model never supplies a value the system can compute or verify itself.** Concretely: account references are resolved against the account registry (a deterministic tool) — a reference that does not resolve is dropped to `unverified`, never routed on; deadlines are re-parsed from the source text by a deterministic date parser, and the model's proposal is discarded in favor of the parsed value; requester identity is matched against the sender address before being trusted. Each field in the TriageRecord carries a provenance marker (`computed`, `verified`, `model-proposed`); the RoutingPort refuses, fail-closed, any record whose action-bearing fields are still `model-proposed`. Records that fail the guard go to the human review queue with the failure reason attached.
+
+## Alternatives discarded
+
+- **Trust the model's structured output**: discarded. Schema-valid is not correct — a well-formed fabricated account reference passes every JSON check and still routes to the wrong customer. Structure guarantees shape, not truth.
+- **Second model call as verifier**: discarded. A verifier model has the same failure class as the extractor; it converts a deterministic check the system can do for free into a probabilistic one that costs tokens. Verification that can be computed must be computed.
+- **Post-hoc detection (flag anomalies after routing)**: discarded. Detection after the action is too late for deadline-bearing compliance requests; the framing note's attached condition demands the miss never happen, not that it be noticed.
+
+## Consequences
+
+- **Positive**: no fabricated value can trigger an action; the guard is pure and unit-testable without a model in the loop; provenance markers make every routing decision auditable field by field; regressions surface at the boundary, in tests, not in the ticketing system.
+- **Negative, accepted**: every deterministic check needs a maintained data source (account registry access, date-parsing rules), and legitimate requests with unresolvable references land in human review — an accepted false-positive cost, since review is cheaper than misrouting.
+- **On other boundaries**: the TriageRecord contract gains the provenance marker (additive, v1.0); the observability schema logs guard outcomes per field, which feeds the evaluation rubric; the middleware chain enforces that RoutingPort is unreachable except through the guard.
+
+## Reevaluation trigger (mandatory, dated)
+
+Reopen this decision if the guard's escalation rate — the share of requests sent to human review because fields stayed unverified — exceeds 25% over two consecutive weeks, measured on the observability schema. That level would mean the deterministic sources are too weak for real traffic and the verification strategy (not the principle) needs redesign. Until then, apply without reopening.
+
+**Trigger set on**: 2026-05-12 · **Watched via**: guard-escalation rate on the weekly observability review
+
+## References
+
+- [architecture.md](../architecture.md) §3 — TriageRecord contract and provenance markers.
+- [ADR-0001](ADR-0001-single-orchestrator.md) — the sequential plan that places this guard before RoutingPort.
+- Framing note §3 — attached condition on compliance-category requests.

package/examples/request-triage/runward/architecture.md

@@ -0,0 +1,64 @@
+# Architecture Note: Inbound Request Triage
+
+**Date**: 2026-05-12 · **Version**: v0.1 · **Framing note**: [framing.md](framing.md) · **ADR journal**: [adr/](adr/)
+
+## 1. Context
+
+The organization triages ~400 heterogeneous inbound requests per week by hand; the success criterion is a first-assignment routing accuracy above the manual baseline, measured on real traffic, with zero silent misses on compliance-category requests. This architecture must carry the floor defined in the framing note: classify, extract key fields, route — nothing more. See [framing.md](framing.md).
+
+## 2. Boundaries
+
+- **Domain ports.** The triage domain is pure: it turns a raw request into a validated triage record and knows nothing about mailboxes, ticketing APIs, or model providers. Every dependency is a contract. The model port is a port like any other — the reasoning engine is bound by its contract (input text in, candidate classification and field extractions out), not by its brand. It is a replaceable adapter behind a stable port, which is also where the data-residency constraint is enforced: the adapter binds to the approved deployment; the domain never sees a provider.
+- **Integration protocol.** Deterministic capabilities (field validation, account lookup, queue resolution) are exposed as tools through a single registry with a middleware chain (logging, access control, cost accounting, approval). Should any capability later move out of process, it is exposed over the standardized tool protocol: a service is an adapter that moved into its own process; the domain does not change.
+
+## 3. Ports
+
+| Port | Direction | Intent | Contract version | Spec |
+|---|---|---|---|---|
+| RequestIntakePort | primary | receive a raw inbound request (mailbox adapter, web-form adapter) | v1.0 | contracts/request-intake.md |
+| ModelPort | secondary | propose classification and field extractions from raw text | v1.0 | contracts/model-port.md |
+| RoutingPort | secondary | assign a validated triage record to a queue in the ticketing system — approval required: only for compliance-flagged records | v1.0 | contracts/routing-port.md |
+| PersistencePort | secondary | append the triage decision to an immutable log, keyed by request ID | v1.0 | contracts/persistence-port.md |
+
+The output contract is the **TriageRecord v1.0** schema: closed category vocabulary (`support`, `sales`, `compliance`, `unknown`), extracted fields each carrying a provenance marker (`computed`, `verified`, `model-proposed`), target queue, confidence level. The contract is versioned and evolves additively; consumers are tolerant readers. A record that fails schema validation is rejected fail-closed, never repaired silently.
+
+## 4. Default topology and triggers
+
+| Default | Rationale | Evolution trigger |
+|---|---|---|
+| Modular hexagonal monolith | one deployable; pure domain plus adapters; 400 req/week needs no distribution | throughput or availability measurably insufficient; multi-instance required |
+| Single orchestrator (ADR-0001) | triage is a short dependent sequence; composes, carries no business logic | a genuinely parallelizable or isolation-requiring subtask appears |
+| Tool registry + middleware chain | single transversal surface for logging, access, cost, approval | — |
+| One core language, thin model SDK | no heavy chain framework; the model is one port among four | mature library or proven performance need → sidecar behind the same port |
+| Deterministic guard before RoutingPort (ADR-0002) | no model-proposed value acts unverified | — (a floor invariant, not a default to outgrow) |
+
+## Rule conformance
+
+| Rule | Status | Evidence |
+|---|---|---|
+| contracts-governance | applied | §3 TriageRecord v1.0 — versioned, additive, tolerant reader, fail-closed; contracts/ |
+| hexa-architecture | applied | §2 pure triage domain, four ports; code/src/core/ |
+| hexa-adapter-pattern | applied | §3 every dependency behind a port; code/src/adapters/ |
+| hexa-typescript-native | n/a | language deliberately left open at this note (§5); locked at floor kickoff (ADR-0003 pending) |
+| process-adr-and-journal | applied | adr/ADR-0001, adr/ADR-0002 — dated decisions with reevaluation triggers |
+| security-mcp-server-pinning | n/a | the floor consumes no MCP or external tool server; tools are in-process and deterministic |
+
+## 5. What stays open
+
+Language, web framework, model provider, and hosting are explicitly undecided at this note's version. Each is an adapter decision, taken behind the contracts above and justified by a local technical reason — the core language will be locked in its own ADR at floor kickoff, chosen for team fluency and SDK maturity, not for the domain, which is language-agnostic by construction.
+
+## 6. Legacy integration
+
+The ticketing system is the system of record and predates this mission. An anticorruption adapter implements RoutingPort and translates the domain's `TriageRecord` into the ticketing API's dialect (its queue identifiers, its custom-field encoding, its pagination quirks). Named cost: the translation table must be maintained when the ticketing configuration changes, and queue resolution requires one extra lookup per routing. Accepted — the alternative is the ticketing dialect leaking into the domain.
+
+## 7. Target, named
+
+Per the framing note: auto-drafted acknowledgments under approval, priority scoring, requester memory, and a reassignment-to-evaluation feedback loop. Each would enter as a new adapter behind a new or existing port, without rewriting the core. Named for direction, not built.
+
+## 8. Decisions
+
+| Decision | ADR |
+|---|---|
+| Single orchestrator, sequential triage | [ADR-0001](adr/ADR-0001-single-orchestrator.md) |
+| Deterministic guard on extracted fields | [ADR-0002](adr/ADR-0002-deterministic-guard-on-extracted-fields.md) |
+| Core language (open — to be locked at floor kickoff) | ADR-0003 (pending) |

package/examples/request-triage/runward/contracts/model-port.md

@@ -0,0 +1,55 @@
+# Port Contract: ModelPort
+
+## Port: ModelPort
+
+**Contract version**: v1.0
+**Port type**: secondary (driven by the domain)
+**Known adapters**: approved-deployment gateway adapter; deterministic keyword fallback classifier
+
+## Business intent
+
+Propose a classification and key-field extractions for one raw request text. The output is a **hypothesis, never a fact**: every proposed value is marked `model-proposed` and nothing downstream may act on it before the deterministic guard (ADR-0002). The reasoning engine is bound by this contract, not by its brand — the fallback classifier honors the same contract with lower recall.
+
+## Signature
+
+```
+propose(requestText) -> triageProposal     — not idempotent, sync, no approval (proposes only, acts on nothing)
+```
+
+## Input schema
+
+| Field | Type | Required | Constraint |
+|---|---|---|---|
+| requestId | uuid | yes | propagated for tracing |
+| requestText | string | yes | subject + body, untrusted; passed as data inside a fixed instruction frame |
+
+## Output schema
+
+| Field | Type | Always present | Constraint |
+|---|---|---|---|
+| category | enum | yes | closed vocabulary: `support`, `sales`, `compliance`, `unknown` |
+| fields | list | yes | may be empty; each entry: name, proposed value, source span in the text |
+| confidence | enum | yes | `high`, `medium`, `low` |
+
+## Invariants
+
+- Every proposed field carries the span of source text it was read from — a value with no span is rejected at the schema.
+- The category never leaves the closed vocabulary; anything else is a validation failure, not a new category.
+- All output is provenance-marked `model-proposed`; this port cannot produce `verified` or `computed` values.
+
+## Errors
+
+| Error | Type | Meaning for the consumer |
+|---|---|---|
+| timeout / overload | transient | retry with bounded backoff, then fall back |
+| non-conforming output | validation | single retry with the diagnostic fed back; then treat as `unknown`, low confidence |
+| gateway unavailable | unavailable | switch to the fallback adapter behind this same port; the domain does not notice |
+
+## Evolution rule
+
+Versioned; the category vocabulary belongs to the TriageRecord contract — extending it (e.g. v1.1 for the unknown-rate trigger, floor.md §5) is a governed, additive contract change gated by a labeled sample, never a free prompt edit.
+
+## References
+
+- [../adr/ADR-0002-deterministic-guard-on-extracted-fields.md](../adr/ADR-0002-deterministic-guard-on-extracted-fields.md) — why this port's output never acts unguarded.
+- [../governance/evaluation-rubric.md](../governance/evaluation-rubric.md) — how this port's behavior is evaluated.

package/examples/request-triage/runward/contracts/persistence-port.md

@@ -0,0 +1,55 @@
+# Port Contract: PersistencePort
+
+## Port: PersistencePort
+
+**Contract version**: v1.0
+**Port type**: secondary (driven by the domain)
+**Known adapters**: append-only store adapter
+
+## Business intent
+
+Append every triage decision to an immutable log, keyed by request ID. The log is the system's truth: audit, replay and recovery all read from it; queue state and metrics are derived views. Nothing is ever updated or deleted — corrections are new entries that reference what they correct.
+
+## Signature
+
+```
+append(triageDecision) -> logPosition      — idempotent on (requestId, step), sync
+readTrajectory(requestId) -> decisionList  — idempotent, sync, read-only
+```
+
+## Input schema
+
+| Field | Type | Required | Constraint |
+|---|---|---|---|
+| requestId | uuid | yes | one trajectory per request |
+| step | enum | yes | `intake`, `proposal`, `guard`, `routing`, `escalation` |
+| payload | object | yes | the step's full record, provenance markers included |
+| recordedAt | timestamp | yes | UTC |
+
+## Output schema
+
+| Field | Type | Always present | Constraint |
+|---|---|---|---|
+| logPosition | integer | yes | strictly increasing; gap-free per trajectory |
+
+## Invariants
+
+- Append-only: no operation on this port mutates or removes an existing entry.
+- A read never mutates state.
+- A trajectory replays in order and completely from its requestId alone — the property verified at the floor gate (floor.md §2, observability check).
+
+## Errors
+
+| Error | Type | Meaning for the consumer |
+|---|---|---|
+| store unavailable | unavailable | fail closed for action-bearing steps: a decision that cannot be persisted does not act (routing blocks); intake buffers at the channel |
+| idempotency conflict | business | same (requestId, step) with different payload — a bug upstream; the entry is refused and the run escalates |
+
+## Evolution rule
+
+Versioned; additive by default — new step types and optional payload fields extend the enum and schema without breaking readers, which tolerate unknown steps. Migrations are forward-only; the log is never rewritten.
+
+## References
+
+- [../governance/observability-schema.md](../governance/observability-schema.md) — lifecycle events persisted through this port.
+- [../runbook.md](../runbook.md) §3 — recovery replays this log, never the model.

package/examples/request-triage/runward/contracts/request-intake.md

@@ -0,0 +1,58 @@
+# Port Contract: RequestIntakePort
+
+## Port: RequestIntakePort
+
+**Contract version**: v1.0
+**Port type**: primary (drives the domain)
+**Known adapters**: mailbox adapter, web-form adapter
+
+## Business intent
+
+Deliver one raw inbound request into the triage domain, whatever channel it arrived on. A "request" here is a single message from one requester asking the organization for something — the channel's envelope (mail headers, form metadata) is normalized at this boundary and never leaks into the domain.
+
+## Signature
+
+```
+submit(rawRequest) -> intakeReceipt        — idempotent on sourceMessageId, sync
+```
+
+## Input schema
+
+| Field | Type | Required | Constraint |
+|---|---|---|---|
+| source | enum | yes | `mailbox` or `web-form` |
+| sourceMessageId | string | yes | channel-native ID; idempotency key |
+| receivedAt | timestamp | yes | channel receipt time, UTC |
+| senderAddress | string | yes | as given by the channel; verified later by the guard, not here |
+| subject | string | no | absent for some form submissions |
+| body | string | yes | raw free text, untrusted by definition |
+
+## Output schema
+
+| Field | Type | Always present | Constraint |
+|---|---|---|---|
+| requestId | uuid | yes | unique; the ID propagated through the whole trajectory |
+| accepted | boolean | yes | false only on validation rejection |
+
+## Invariants
+
+- Every accepted request yields exactly one requestId; resubmitting the same sourceMessageId returns the same one.
+- Intake never mutates the source channel and never triages — it accepts and hands over.
+- The body is stored verbatim; normalization is recorded as derived data, never destructive.
+
+## Errors
+
+| Error | Type | Meaning for the consumer |
+|---|---|---|
+| malformed payload | validation | rejected at the boundary; the channel adapter keeps the original for manual pickup |
+| duplicate sourceMessageId | business | not an error — same receipt returned (idempotent) |
+| store unavailable | unavailable | fail closed: the adapter retries from the channel; nothing is acknowledged unpersisted |
+
+## Evolution rule
+
+Versioned; additive by default (new optional fields, tolerant readers); a breaking change goes expand-then-contract across both channel adapters before the old shape retires.
+
+## References
+
+- [../architecture.md](../architecture.md) §3 — port table.
+- [model-port.md](model-port.md) — next step in the fixed sequential plan.