runward 0.14.2 → 0.16.0

package/examples/request-triage/code/test/triage.test.ts

@@ -0,0 +1,243 @@
+// Test floor of the triage example: classification, deterministic guard on
+// extracted fields, routing, fail-closed compliance (suspend-and-rehydrate),
+// abstention on unknown. Everything deterministic: no model key, no network.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { TriageRequestUseCase } from "../src/core/application/triage-request.usecase.ts";
+import { KeywordModelAdapter } from "../src/adapters/keyword-model.adapter.ts";
+import { HardcodedAccountRegistry } from "../src/adapters/hardcoded-account-registry.adapter.ts";
+import {
+  InMemoryRoutingAdapter,
+  ProvenanceRefusalError,
+  ApprovalMissingError,
+} from "../src/adapters/in-memory-routing.adapter.ts";
+import { InMemoryTriageLog } from "../src/adapters/in-memory-triage-log.adapter.ts";
+import { parseDeadline } from "../src/core/domain/guard.ts";
+import type { TriageModelPort } from "../src/core/ports/model-provider.port.ts";
+import type { TriageRecord } from "../src/core/domain/triage.ts";
+
+const fixedClock = { nowIso: () => "2026-06-01T00:00:00.000Z" };
+
+function buildRig(model?: TriageModelPort) {
+  const routing = new InMemoryRoutingAdapter();
+  const log = new InMemoryTriageLog();
+  const useCase = new TriageRequestUseCase({
+    model: model ?? new KeywordModelAdapter(),
+    registry: new HardcodedAccountRegistry(),
+    routing,
+    log,
+    clock: fixedClock,
+  });
+  return { useCase, routing, log };
+}
+
+// --- Classification and routing ---------------------------------------------
+
+test("support request: classified and routed to the support queue", async () => {
+  const { useCase } = buildRig();
+  const res = await useCase.triage({
+    requestId: "r1",
+    senderAddress: "jane@acme.example",
+    body: "The export keeps failing with an error, please help. Account ACC-1001.",
+  });
+  assert.equal(res.record.category, "support");
+  assert.equal(res.status, "routed");
+  assert.equal(res.targetQueue, "support-queue");
+  assert.ok(res.ticketRef);
+});
+
+test("sales request: classified and routed to the sales queue", async () => {
+  const { useCase } = buildRig();
+  const res = await useCase.triage({
+    requestId: "r2",
+    senderAddress: "buyer@globex.example",
+    body: "We would like a pricing quote for 50 seats.",
+  });
+  assert.equal(res.record.category, "sales");
+  assert.equal(res.status, "routed");
+  assert.equal(res.targetQueue, "sales-queue");
+});
+
+test("compliance beats overlapping signals: a privacy request that also says 'help' is compliance", async () => {
+  const { useCase } = buildRig();
+  const res = await useCase.triage({
+    requestId: "r3",
+    senderAddress: "dpo@initech.example",
+    body: "Please help us process this GDPR data deletion request.",
+  });
+  assert.equal(res.record.category, "compliance");
+});
+
+// --- Abstention ---------------------------------------------------------------
+
+test("unknown category: the system abstains, nothing is routed", async () => {
+  const { useCase, routing } = buildRig();
+  const res = await useCase.triage({
+    requestId: "r4",
+    senderAddress: "someone@example.org",
+    body: "Following up on the thing from last month.",
+  });
+  assert.equal(res.record.category, "unknown");
+  assert.equal(res.status, "needs_review");
+  assert.equal(res.targetQueue, "review-queue");
+  assert.equal(routing.assignments, 0); // abstention: no action taken
+});
+
+// --- Deterministic guard on extracted fields (ADR-0002) -----------------------
+
+test("guard: an account reference that resolves in the registry is verified", async () => {
+  const { useCase } = buildRig();
+  const res = await useCase.triage({
+    requestId: "r5",
+    senderAddress: "jane@acme.example",
+    body: "Login is broken for account ACC-1001.",
+  });
+  assert.equal(res.record.accountRef?.value, "ACC-1001");
+  assert.equal(res.record.accountRef?.provenance, "verified");
+  assert.equal(res.record.accountRef?.accountName, "Acme Corp");
+});
+
+test("guard: a fabricated account reference never routes — escalated to review", async () => {
+  const { useCase, routing } = buildRig();
+  const res = await useCase.triage({
+    requestId: "r6",
+    senderAddress: "jane@acme.example",
+    body: "Our app crashes constantly. Account ACC-9999.", // not in the registry
+  });
+  assert.equal(res.status, "needs_review");
+  assert.ok(res.reason?.includes("ACC-9999"));
+  assert.equal(routing.assignments, 0); // fail-closed: no routing happened
+});
+
+test("guard: the deadline is re-parsed from the source text; the model's proposal is discarded", async () => {
+  // Adversarial model stub: proposes a WRONG deadline (and a valid category).
+  const lyingModel: TriageModelPort = {
+    async propose() {
+      return {
+        category: "support",
+        confidence: "high",
+        fields: [{ name: "deadline", value: "2099-12-31", sourceSpan: "made up" }],
+      };
+    },
+  };
+  const { useCase } = buildRig(lyingModel);
+  const res = await useCase.triage({
+    requestId: "r7",
+    senderAddress: "jane@acme.example",
+    body: "The report is broken and we need it fixed by 2026-07-15.",
+  });
+  // The system's value comes from the deterministic parser, not the model.
+  assert.equal(res.record.deadline?.value, "2026-07-15");
+  assert.equal(res.record.deadline?.provenance, "computed");
+});
+
+test("guard: the deadline parser rejects well-shaped non-dates", () => {
+  assert.equal(parseDeadline("due 2026-13-45, then 2026-02-30"), null);
+  assert.equal(parseDeadline("due 2026-02-28"), "2026-02-28");
+});
+
+// --- Fail-closed compliance: suspend and rehydrate ----------------------------
+
+test("compliance: suspended awaiting approval, never routed silently", async () => {
+  const { useCase, routing, log } = buildRig();
+  const res = await useCase.triage({
+    requestId: "r8",
+    senderAddress: "dpo@initech.example",
+    body: "GDPR erasure request for ACC-3003, respond by 2026-08-01.",
+  });
+  assert.equal(res.status, "suspended");
+  assert.equal(routing.assignments, 0); // fail-closed: nothing routed yet
+  // The trajectory is serialized: the exact validated record awaits.
+  const pending = await log.getPending("r8");
+  assert.equal(pending?.record.accountRef?.value, "ACC-3003");
+  // The approval summary is deterministic, built from the validated fields.
+  assert.ok(pending?.summary.includes("ACC-3003 (verified)"));
+  assert.ok(pending?.summary.includes("2026-08-01 (computed)"));
+  assert.equal(res.reason, pending?.summary);
+});
+
+test("compliance resume approve: routed to the compliance queue with the approval recorded", async () => {
+  const { useCase, log } = buildRig();
+  await useCase.triage({
+    requestId: "r9",
+    senderAddress: "dpo@initech.example",
+    body: "GDPR data access request for ACC-3003.",
+  });
+  const resumed = await useCase.resumeTriage("r9", "approve", "ops-coordinator");
+  assert.equal(resumed.status, "routed");
+  assert.equal(resumed.targetQueue, "compliance-queue");
+  assert.ok(resumed.ticketRef);
+  assert.equal(await log.getPending("r9"), null); // suspension point cleared
+  const journal = await log.read("r9");
+  assert.ok(journal.some((e) => e.event === "approval_decision"));
+});
+
+test("compliance resume reject: the routing never happens", async () => {
+  const { useCase, routing, log } = buildRig();
+  await useCase.triage({
+    requestId: "r10",
+    senderAddress: "dpo@initech.example",
+    body: "Privacy complaint escalated by the regulator, account ACC-2002.",
+  });
+  const resumed = await useCase.resumeTriage("r10", "reject", "ops-coordinator");
+  assert.equal(resumed.status, "rejected");
+  assert.equal(routing.assignments, 0); // never executed
+  assert.equal(await log.getPending("r10"), null);
+});
+
+// --- Routing port invariants ---------------------------------------------------
+
+test("routing port refuses, fail-closed, a record with model-proposed action-bearing fields", async () => {
+  const routing = new InMemoryRoutingAdapter();
+  const record: TriageRecord = {
+    requestId: "r11",
+    category: "support",
+    confidence: "high",
+    accountRef: { value: "ACC-1001", provenance: "model-proposed" },
+  };
+  await assert.rejects(
+    () => routing.assign(record, "support-queue"),
+    ProvenanceRefusalError,
+  );
+  // And a compliance record without a recorded approval is refused too.
+  const compliance: TriageRecord = {
+    requestId: "r12",
+    category: "compliance",
+    confidence: "high",
+  };
+  await assert.rejects(
+    () => routing.assign(compliance, "compliance-queue"),
+    ApprovalMissingError,
+  );
+});
+
+test("routing port is idempotent on requestId: no duplicate tickets", async () => {
+  const routing = new InMemoryRoutingAdapter();
+  const record: TriageRecord = {
+    requestId: "r13",
+    category: "support",
+    confidence: "high",
+  };
+  const first = await routing.assign(record, "support-queue");
+  const second = await routing.assign(record, "support-queue");
+  assert.equal(first.ticketRef, second.ticketRef);
+  assert.equal(routing.assignments, 1);
+});
+
+// --- Boundary -------------------------------------------------------------------
+
+test("input boundary: a malformed payload is rejected, unknown keys included", async () => {
+  const { useCase } = buildRig();
+  await assert.rejects(() =>
+    useCase.triage({ requestId: "", senderAddress: "a@b.c", body: "x" }),
+  );
+  await assert.rejects(() =>
+    useCase.triage({
+      requestId: "r14",
+      senderAddress: "a@b.c",
+      body: "hello",
+      role: "admin",
+    } as never),
+  );
+});

package/examples/request-triage/code/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts"]
+}

package/examples/request-triage/runward/adr/ADR-0003-port-placement-and-sovereignty.md

@@ -0,0 +1,44 @@
+# ADR-0003: port placement and sovereignty behind the four ports
+
+**Date**: 2026-05-12
+**Status**: accepted
+**Deciders**: operator, Head of Operations (sponsor)
+**Method**: decision-loop: reality-check against the org's existing infrastructure inventory, challenge on sovereignty per data class, durable position
+
+## Context
+
+The architecture note names four ports; two of their adapters run beyond the process. The model adapter calls a vendor-hosted deployment, and the routing adapter writes into the ticketing system the organization already operates. Placement is an adapter decision behind a stable port — the domain does not change with it — but it is a decision, and it carries the mission's most sensitive constraint: inbound request text may contain personal data, so where each adapter runs decides which jurisdiction and which operator can read it. This ADR is the first member of the mission's infra ADR family (placement, sovereignty, trace export); it locks the placement and sovereignty rows recorded in `execution-topology.md`.
+
+## Decision
+
+One placement per port, sovereignty graduated by the class of data crossing it — never a wholesale switch.
+
+- **ModelPort → managed model-vendor runtime**, bound to the organization's approved deployment. Residency is enforced at the adapter: the deployment is region-pinned, and request text (internal, possibly personal) never leaves the approved region. Sovereignty: **raised**. The port keeps the placement reversible — a self-hosted or gateway-fronted deployment is an adapter swap, not a rework.
+- **RoutingPort → existing infrastructure** (the ticketing system of record), reached only through the anticorruption adapter and the deterministic guard (ADR-0002). Only the validated `TriageRecord` (internal business data) crosses; compliance-flagged records are approval-gated. Sovereignty: **standard**.
+- **RequestIntakePort and PersistencePort → in-app**, the sober default; the intake adapter consumes the existing mailbox, the log is in-process and append-only.
+- **No third-party trace export.** Observability is in-app structured logs (`governance/observability-schema.md`). Traces carry request text — exporting them would be a data transfer requiring its own ADR naming recipient, data class and retention.
+
+## Alternatives discarded
+
+- **Self-hosted model runtime**: discarded at the floor. Operating a model server costs more than the floor's value proof justifies, and the port makes the move cheap later. Trigger named below.
+- **A dedicated intake queue now**: discarded. No volume signal; in-process handling holds the observed load. Premature distribution would buy eventual consistency and idempotence work with no gain.
+- **Exporting traces to a managed observability service**: discarded. Traces contain the prompts and the extracted fields — the most sensitive payloads in the system. Convenience does not clear a data transfer; if the need appears, it is its own decision with recipient, class and retention named.
+
+## Consequences
+
+- **Positive**: every port's placement and sovereignty is a traced, reversible decision; residency is pinned where it is actually enforced (the adapter binding, not a policy document); the two non-in-app placements are auditable from one table.
+- **Negative, accepted**: the model path depends on a vendor runtime — bounded by the port and the approved-deployment binding; the ticketing coupling is real but contained in the anticorruption adapter.
+- **On other boundaries**: `execution-topology.md` §2 records the rows this ADR locks; the usage registry (§3) classes the deployment's risk; the threat model treats both external surfaces as untrusted.
+
+## Reevaluation trigger (mandatory, dated)
+
+Reopen this decision if any of: a second application needs the same model routing, quotas or audit (→ shared gateway on existing infra); the ticketing system is migrated or multi-tenanted; anyone requests third-party trace export; or the data classification of inbound requests changes (e.g. confirmed regulated data). Until a trigger fires, apply without reopening.
+
+**Trigger set on**: 2026-05-12 · **Watched via**: the usage registry review at each iterate gate, and the architecture review before any new consumer of the model path
+
+## References
+
+- [execution-topology.md](../execution-topology.md) §2 — the port → placement map this ADR locks.
+- [architecture.md](../architecture.md) §2, §3 — the ports and the data residency constraint.
+- [shared-bricks.md](../shared-bricks.md) — the five location families and six criteria used to arbitrate.
+- [ADR-0002](ADR-0002-deterministic-guard-on-extracted-fields.md) — the guard standing before RoutingPort.

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

@@ -39,8 +39,8 @@ The output contract is the **TriageRecord v1.0** schema: closed category vocabul
 | 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 |
+| hexa-typescript-native | n/a | language deliberately left open at this note (§5); locked at floor kickoff (ADR-0004 pending) |
+| process-adr-and-journal | applied | adr/ADR-0001, adr/ADR-0002, adr/ADR-0003 — 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
@@ -61,4 +61,5 @@ Per the framing note: auto-drafted acknowledgments under approval, priority scor
 |---|---|
 | 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) |
+| Port placement and sovereignty (the infra ADR family) | [ADR-0003](adr/ADR-0003-port-placement-and-sovereignty.md) |
+| Core language (open — to be locked at floor kickoff) | ADR-0004 (pending) |

package/examples/request-triage/runward/decision-matrix.md

@@ -1,6 +1,6 @@
 # Decision Matrix
 
-**Mission state (2026-05-12, Architect gate)** — matrix adopted as the arbitration reference for this mission. Positions taken so far, all on the sober default: number of agents → single orchestrator, locked in [ADR-0001](adr/ADR-0001-single-orchestrator.md); untrusted input and deterministic frontier → guard on extracted fields, locked in [ADR-0002](adr/ADR-0002-deterministic-guard-on-extracted-fields.md); core language → open, to be locked at floor kickoff (ADR-0003, pending). No trigger has fired; watched signals are tracked in [floor.md](floor.md) §4.
+**Mission state (2026-05-12, Architect gate)** — matrix adopted as the arbitration reference for this mission. Positions taken so far, all on the sober default: number of agents → single orchestrator, locked in [ADR-0001](adr/ADR-0001-single-orchestrator.md); untrusted input and deterministic frontier → guard on extracted fields, locked in [ADR-0002](adr/ADR-0002-deterministic-guard-on-extracted-fields.md); port placement and sovereignty → the two non-in-app placements locked in [ADR-0003](adr/ADR-0003-port-placement-and-sovereignty.md); core language → open, to be locked at floor kickoff (ADR-0004, pending). No trigger has fired; watched signals are tracked in [floor.md](floor.md) §4.
 
 How to use this file: every structural decision below carries **one sober default and one explicit trigger**. You start on the default. You only move when the trigger fires — measured, observed, named. **No trigger, no change. Every switch is an ADR** (`runward/adr/`), with the evidence that fired the trigger and a date to re-evaluate. Fill the matrix during the Architect phase; reopen it at every Iterate gate.
 

package/examples/request-triage/runward/execution-topology.md

@@ -11,8 +11,8 @@ The triage domain says *what* the system does (raw request in, validated `Triage
 | Port | Adapter (what runs) | Location family | Data class(es) crossing it | Sovereignty level | ADR / evidence | Re-evaluation trigger |
 |---|---|---|---|---|---|---|
 | RequestIntakePort | mailbox / web-form adapter, in-process | In-app, consuming existing infra (mailbox) | inbound request text (internal, may carry personal data) | raised | architecture.md §3 | intake volume outgrows in-process handling → dedicated queue |
-| ModelPort | model adapter bound to the approved deployment | Managed model-vendor runtime | request text (internal / personal) | raised — residency enforced at the adapter, not in the domain | architecture.md §2 (data residency at the port) | a second application needs the same routing/quotas → shared model gateway |
-| RoutingPort | anticorruption adapter → ticketing system of record | Existing infrastructure | `TriageRecord` (internal business) | standard; approval-gated for compliance-flagged records | architecture.md §"Legacy integration"; ADR-0002 (deterministic guard) | the ticketing system moves or multi-tenants → re-evaluate the adapter placement |
+| ModelPort | model adapter bound to the approved deployment | Managed model-vendor runtime | request text (internal / personal) | raised — residency enforced at the adapter, not in the domain | ADR-0003 (placement + residency); architecture.md §2 | a second application needs the same routing/quotas → shared model gateway |
+| RoutingPort | anticorruption adapter → ticketing system of record | Existing infrastructure | `TriageRecord` (internal business) | standard; approval-gated for compliance-flagged records | ADR-0003 (placement); ADR-0002 (deterministic guard) | the ticketing system moves or multi-tenants → re-evaluate the adapter placement |
 | PersistencePort | append-only log, in-process | In-app | `TriageRecord` plus provenance (internal) | standard | architecture.md §3 | multi-instance required → externalized store (iterate) |
 
 Traces are data: this floor exports none to a third party (see the conformance note below).
@@ -29,7 +29,7 @@ Risk is classed by deployment, not by platform. This floor is one deployment.
 
 | Rule | Status | Evidence |
 |---|---|---|
-| topology-port-placement-mapped | applied | §2 map — all four ports placed; the two non-in-app placements (ModelPort → managed vendor runtime under an approved deployment, RoutingPort → existing ticketing infra) are recorded in architecture.md §2 and the legacy-integration note |
+| topology-port-placement-mapped | applied | §2 map — all four ports placed; the two non-in-app placements (ModelPort → managed vendor runtime, RoutingPort → existing ticketing infra) are locked in ADR-0003 (the infra ADR family) |
 | topology-sovereignty-by-data-class | applied | §2 map — a data class and a sovereignty level per port; request text is bound to the approved model deployment (residency), the `TriageRecord` is kept internal |
 | topology-trace-export-decision | n/a | the floor exports no execution traces to a third party; observability is in-app structured logs per governance/observability-schema.md |
 | topology-usage-registry-present | applied | §3 usage registry — the single prod deployment with its risk class, data classes, action scopes and owner |

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

@@ -19,15 +19,15 @@
 
 | Rule | Status | Evidence |
 |---|---|---|
-| frontier-deterministic-boundary | applied | code/src/core/domain/guard.ts — every action-bearing field recomputed/verified (ADR-0002), fail-closed |
-| hexa-move-deterministic-out | applied | code/src/core/domain/guard.ts + keyword classifier — classification and validation are deterministic |
+| frontier-deterministic-boundary | applied | file:code/src/core/domain/guard.ts#guardFields; test:code/test/triage.test.ts — every action-bearing field recomputed/verified (ADR-0002), fail-closed |
+| hexa-move-deterministic-out | applied | file:code/src/core/domain/guard.ts#parseDeadline — classification and validation are deterministic, out of the model |
 | config-secrets-boundary | n/a | the illustrative floor runs the deterministic keyword classifier; no provider secret is read in this example code |
 | provider-llm-auto-detection | n/a | only the deterministic keyword adapter ships here; no real provider to auto-detect |
 | security-prompt-injection | applied | threat-model §3 + ADR-0002 — model-proposed values never act; request text is data, not instruction |
 | hexa-architecture | applied | code/src/core/ pure domain behind four ports |
 | hexa-adapter-pattern | applied | code/src/adapters/ — mailbox/web, keyword-model, routing, log behind ports |
-| provider-no-crash-missing-env | applied | code/src/adapters/keyword-model.adapter.ts — deterministic fallback runs with no key |
-| state-event-sourcing | applied | code/src/adapters/in-memory-triage-log.adapter.ts — append-only, keyed by request ID |
+| provider-no-crash-missing-env | applied | file:code/src/adapters/keyword-model.adapter.ts — deterministic fallback runs with no key |
+| state-event-sourcing | applied | file:code/src/adapters/in-memory-triage-log.adapter.ts — append-only, keyed by request ID |
 | tools-scope-atomicity | applied | architecture §2 middleware chain + approval on RoutingPort for compliance records |
 
 ## 2. Proof against the success criterion

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

@@ -0,0 +1,47 @@
+# Hand-over Note — Request Triage
+
+**Date**: 2026-07-03 · **Departing builder**: the mission operator · **Receiving side**: operations team (triage product owner) · All names and dates **illustrative**, like the rest of the reference mission.
+
+## 1. The kit
+
+| Artifact | Where | State | Exercised by the receiving side? |
+|---|---|---|---|
+| Recovery runbook | `runbook.md` | ready | 2026-06-30 — ops engineer ran the recovery replay (§3) during the drill |
+| Agent charter (finalized) | `AGENTS.md` (project root) | finalized at hand-over | read and countersigned at the second transfer session |
+| Architecture note + decision journal | `architecture.md` · `adr/` (3 ADRs, triggers dated) | current | walked through, hands on keyboard |
+| Evaluation bench | `cd code && npm test` + the replay set (floor.md §2) | ready | 2026-07-02 — re-run alone (see §2) |
+| Evidence pack | `compliance/` — regenerate with `runward compliance <regime>` | regenerable on demand | generated once by the ops engineer during the drill |
+
+## 2. The redone task (the proof)
+
+- **Task**: after the illustrative provider incident of 2026-06-29 (gateway timeouts, fallback classifier engaged — runbook §4 first row), re-run the full behavioral proof and the demo, then process the suspended compliance approval that had queued during the incident — end to end, from the leave-behinds alone.
+- **Date / doer**: 2026-07-02, the operations engineer of the receiving team; the builder unavailable by agreement (out of the loop for the day).
+- **Evidence**: file:code/test/triage.test.ts; file:runward/runbook.md#Recovery — the proof re-ran green, the replay recovered the queued state, the suspended approval was released through the approval path (ADR-0002 provenance rules held).
+- **Gaps found**: two, both folded back the same day — the runbook did not name where the review queue persists (added to §3), and the demo's expected output was undocumented (added to the code README).
+
+## 3. Succession
+
+- **Owner after departure**: the triage product owner (operations) — incidents, cost, credentials, and the three open ADR re-evaluation triggers.
+- **Escalation path**: compliance officer for category/vocabulary questions; the sponsor (Head of Operations) for scope; provider support through the gateway contract.
+- **Review cadence**: the usage registry and the ADR triggers are re-read at the weekly observability review (the guard-escalation rate of ADR-0002 is already on its agenda); the evidence seal is re-taken at each gate crossing.
+- **Credentials boundary**: ticketing and gateway credentials live in the ops vault, injected at the network boundary; the builder's accesses were revoked on 2026-07-03 as part of this note.
+
+## 4. Provider-swap drill
+
+2026-06-27 — swapped the model adapter from the approved gateway deployment to the deterministic keyword fallback and back (the adapter switch of architecture.md §2), then re-ran the bench: accuracy on the replay set within the expected fallback envelope, provenance rules unaffected. The port held; the domain never noticed. Next drill on the shared-gateway trigger (ADR-0003).
+
+## Rule conformance
+
+| Rule | Status | Evidence |
+|---|---|---|
+| handover-redone-task-proof | applied | §2 — 2026-07-02, ops engineer, incident-recovery task end to end without the builder; file:code/test/triage.test.ts; file:runward/runbook.md#Recovery |
+| handover-runbook-executable | applied | file:runward/runbook.md#Recovery — the seven gestures carry commands/paths (start §1, observe §1, debug §4, resume §3, swap §2+§4, bench: cd code && npm test, approvals §3); exercised during the 2026-07-02 task |
+| handover-agents-charter-final | applied | file:AGENTS.md#Never — finalized at hand-over: mission-specific boundaries (registry read-only, compliance always approval-gated), exact verification commands, never/PR rules |
+| handover-succession-named | applied | §3 — named owner (triage product owner), escalation path, weekly review cadence, builder's accesses revoked 2026-07-03 |
+
+## Cross-references
+
+- `workflows/handover.md` — the phase this note closes.
+- `runbook.md` — the operational half of the kit.
+- `AGENTS.md` — the charter the next agent inherits.
+- `adr/` — the open re-evaluation triggers the owner now watches.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "runward",
-  "version": "0.14.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.",
+  "version": "0.16.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.",
   "keywords": [
     "agentic",
     "ai-agents",
@@ -22,31 +22,44 @@
     "url": "https://github.com/stranxik/runward/issues"
   },
   "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
   "bin": {
     "runward": "dist/cli.js"
   },
   "files": [
     "dist",
     "templates",
+    "regimes",
+    "examples/request-triage/AGENTS.md",
     "examples/request-triage/runward",
+    "examples/request-triage/code/src",
+    "examples/request-triage/code/test",
+    "examples/request-triage/code/package.json",
+    "examples/request-triage/code/tsconfig.json",
+    "examples/request-triage/code/README.md",
     "README.md",
-    "NOTICE.md"
+    "NOTICE.md",
+    "LICENSE"
   ],
   "engines": {
     "node": ">=20"
   },
   "scripts": {
     "build": "tsc",
-    "test": "npm run build && node test/smoke.js && node test/oscal-schema.js",
-    "prepublishOnly": "npm run build && node test/smoke.js && node test/oscal-schema.js"
+    "test": "npm run build && node --test test/unit/*.test.js && node test/smoke.js && node test/oscal-schema.js",
+    "test:unit": "npm run build && node --test test/unit/*.test.js",
+    "coverage": "npm run build && node --test --experimental-test-coverage test/unit/*.test.js",
+    "prepublishOnly": "npm run build && node --test test/unit/*.test.js && node test/smoke.js && node test/oscal-schema.js"
   },
   "dependencies": {
-    "@inquirer/prompts": "^7.0.0",
+    "@inquirer/prompts": "^8.5.2",
     "chalk": "^5.6.0",
-    "commander": "^14.0.0"
+    "commander": "^15.0.0"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
+    "@types/node": "^26.1.1",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "js-yaml": "^5.2.1",

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

@@ -0,0 +1,31 @@
+{
+  "_comment": "Regime mapping data (ADR-0022). Cut line: this file carries only what tracks Regulation (EU) 2024/1689 — the Annex III applicability date, the article references, the Annex IV point-by-point coverage rows, and the provider-required list. runward's stable product voice stays in src/lib/compliance.ts. An Annex IV amendment or corrigendum is a NEW regimes/eu-ai-act@<version>.json, never an edit of this file.",
+  "regime": "eu-ai-act",
+  "label": "EU AI Act (Annex IV)",
+  "version": "2024-1689",
+  "notes": "Mapped 2026-07 against Regulation (EU) 2024/1689 (OJ L, 12 July 2024). High-risk (Annex III) obligations bind from 2 August 2026. Annex IV wording moves — confirm against the Official Journal before filing.",
+  "highRisk": {
+    "bindFrom": "2 August 2026",
+    "scope": "Annex III"
+  },
+  "articles": {
+    "runtimeLogging": "art. 12"
+  },
+  "annexIv": [
+    { "point": "1. General description", "supplies": "UI, HW/SW/firmware notes", "provider": "intended purpose, provider, versioning, distribution" },
+    { "point": "2. Elements & development", "supplies": "**architecture, validation procedures + metrics, cybersecurity (manifest + rubric + threat model); design choices, alternatives, assumptions, pre-determined changes = the ADR journal**", "provider": "third-party sourcing/licensing, sign-off on test logs" },
+    { "point": "3. Monitoring & control", "supplies": "accuracy characterization, input-data specs, oversight tooling", "provider": "fundamental-rights / discrimination risk sourcing" },
+    { "point": "4. Performance metrics", "supplies": "metric-choice justification (rubric)", "provider": "—" },
+    { "point": "5. Risk management (art. 9)", "supplies": "technical inputs (threat model, testing)", "provider": "**risk acceptance / RMS governance**" },
+    { "point": "6. Lifecycle changes", "supplies": "engineering change record (ADR journal)", "provider": "release/change-management governance" },
+    { "point": "7. Harmonised standards", "supplies": "technical notes", "provider": "**standards selection** (compliance strategy)" },
+    { "point": "8. Declaration of conformity", "supplies": "—", "provider": "**signed legal act (art. 47)**" },
+    { "point": "9. Post-market monitoring", "supplies": "telemetry/logging backbone", "provider": "**post-market monitoring plan (art. 72)**" }
+  ],
+  "operatorRequired": [
+    "**Point 1** general description (intended purpose, provider, versioning) · **Point 5** RMS governance & risk acceptance (art. 9).",
+    "**Point 7** harmonised-standards selection · **Point 8** the signed **EU declaration of conformity** (art. 47) · **Point 9** the **post-market monitoring plan** (art. 72).",
+    "**Art. 12 runtime event logs** — produced by the running system, not by runward."
+  ],
+  "disclaimerTail": "Annex IV wording moves — confirm against the Official Journal (Reg. (EU) 2024/1689) before filing."
+}

package/regimes/iso-42001@2023.json

@@ -0,0 +1,22 @@
+{
+  "_comment": "Regime mapping data (ADR-0022). Cut line: this file carries only what tracks the ISO/IEC 42001:2023 text — clause references used in the draft, the operator-required clause list, and the dated caveat. runward's stable product voice (draft framing, section narrative, table glue) stays in src/lib/compliance.ts. A revision of the standard is a NEW regimes/iso-42001@<version>.json, never an edit of this file.",
+  "regime": "iso-42001",
+  "label": "ISO/IEC 42001",
+  "version": "2023",
+  "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",
+    "controlSelection": "6.1.3",
+    "annexControls": "Annex A"
+  },
+  "operatorRequired": [
+    "**AI policy** (5.2) and **AIMS scope** (4.3).",
+    "**Statement of Applicability — the applicability decisions and inclusion/exclusion justifications** (6.1.3): runward supplies the status + evidence columns; the *applicability* judgment is yours.",
+    "**Risk methodology, acceptance criteria and risk-acceptance decisions** (6.1.2, 8.3).",
+    "**AI system impact assessment report and deployment authorization** (6.1.4).",
+    "**Objectives and targets** (6.2), **roles and competence** (A.3, 7.2).",
+    "**Internal audit** (9.2) and **management review** minutes (9.3).",
+    "**Runtime AI event logs** (A.6.2.8) — produced by the running system, not by runward."
+  ],
+  "disclaimerTail": "ISO Annex A control counts/templates are behind the paywalled standard — confirm against the purchased text."
+}

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

@@ -0,0 +1,19 @@
+{
+  "_comment": "Regime mapping data (ADR-0022). Cut line: this file carries only what tracks NIST AI 100-1 (AI RMF 1.0, January 2023) — the ASI crosswalk target functions, the MEASURE reference, and the operator-required function list. runward's stable product voice stays in src/lib/compliance.ts. An AI RMF update is a NEW regimes/nist-ai-rmf@<version>.json, never an edit of this file.",
+  "regime": "nist-ai-rmf",
+  "label": "NIST AI RMF",
+  "version": "1.0",
+  "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)",
+    "confirmAgainst": "AI RMF §5"
+  },
+  "measureRef": "MEASURE 2.x",
+  "operatorRequired": [
+    "**GOVERN** — policies, roles, accountability, **risk tolerance** (almost entirely organizational).",
+    "**MAP** — intended purpose, business/legal context, use-case risk enumeration.",
+    "**MANAGE** — the **go/no-go acceptance** decision, resourcing, response planning.",
+    "**Profiles** — Current/Target selection, prioritization, the risk-tolerance choices behind them."
+  ],
+  "disclaimerTail": "NIST prescribes no report template — confirm against AI 100-1 and the Playbook."
+}

package/templates/adapters/README.md

@@ -39,12 +39,20 @@ A non-zero exit aborts the commit. Bypass a single commit with `git commit --no-
 
 Copy the job into a workflow under `.github/workflows/` (or merge it into an existing one). Make it a required status check on your protected branch so no gap merges. This is the audit-evidence seam for a regulated pipeline: a dated, versioned record that the gate passed on every merge.
 
+## `gitlab-ci.yml` — the same required check, GitLab flavor
+
+Merge the job into your `.gitlab-ci.yml` and require the pipeline on your protected branch (Settings → Merge requests). Same port, same one line — the gate does not care which forge reads its exit code.
+
 ## `claude-code-settings.json` — run the gate at the agent's turn-end (one example)
 
 Merge the `hooks` block into your `.claude/settings.json` (or `.claude/settings.local.json`). The `Stop` hook runs the gate when the agent finishes a turn and surfaces the verdict in the loop — so an agent can no longer close out with the gate never run.
 
 This is **one example** of a per-harness turn-end hook, not a privileged one — Claude Code just happens to expose a clean, documented seam. Any agent harness that can run a command at turn-end (Codex, and others as they add the capability) wires the *same* one line: `runward check --strict`. And where a harness offers no such seam, the `pre-commit` and CI adapters above already gate the code **whatever agent produced it** — the port is the exit code, not the agent.
 
+## `kiro-hooks.json` — the same turn-end gate, Kiro flavor
+
+Copy the file into `.kiro/hooks/` in your workspace. The `Stop` trigger runs `runward check --strict` when the agent finishes, and surfaces the verdict in the session — the same one line as the Claude Code hook, another non-privileged example of a per-harness turn-end seam. Kiro also reads `AGENTS.md` natively, and `runward init --tools kiro` mirrors the phase skills as steering files (`.kiro/steering/`, relevance-loaded) — the traced decisions inform the session; the gate stays the only authority.
+
 ---
 
 Adapters are runward-owned templates: `runward update` refreshes them, `runward doctor` verifies them. They are never mission state. Add a new harness by dropping a new sample here — the port contract above does not change.

package/templates/adapters/gitlab-ci.yml

@@ -0,0 +1,18 @@
+# runward gate — GitLab CI adapter (sample).
+# Inert until you install it: see runward/adapters/README.md.
+# Merge this job into your .gitlab-ci.yml, then make the pipeline required
+# on your protected branch (Settings → Merge requests → pipelines must
+# succeed) so no gap merges.
+#
+# The gate is deterministic and zero-LLM: no secrets, no model key needed.
+# Exit codes (the port contract): 0 clean · 1 gaps · 2 no mission found.
+
+runward-gate:
+  image: node:20
+  # Use --strict to also enforce the rule-conformance manifests.
+  # Drop --strict for the deliverable audit only.
+  script:
+    - npx --yes runward check --strict
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

package/templates/adapters/kiro-hooks.json

@@ -0,0 +1,12 @@
+{
+  "version": "v1",
+  "hooks": [
+    {
+      "name": "runward-gate",
+      "trigger": "Stop",
+      "action": { "type": "command", "command": "npx --yes runward check --strict" },
+      "timeout": 120,
+      "enabled": true
+    }
+  ]
+}

package/templates/mission/architecture.md

@@ -40,6 +40,8 @@
 ## Rule conformance
 
 > Account for every CRITICAL/HIGH craft rule mapped to the architect phase (`runward/rules/`, frontmatter `phases: [architect]`). `applied` needs a pointer; `deviated` needs an ADR; `n/a` needs a reason. `runward check --strict` verifies this table is complete — it checks a traced decision, not the quality of your architecture.
+>
+> Evidence can be **typed**, and typed pointers are verified deterministically at the gate: `file:PATH[:LINE][#SYMBOL]` · `test:PATH[::NAME]` · `adr:NNNN` — several per cell, separated by `;`. The gate checks resolution, non-emptiness, line count, symbol/test-name presence, and the rule's `signature:` when it declares one (ADR-0019/0020). Free prose stays valid — it is your judgment; a path it cites must simply not point at an empty file.
 
 | Rule | Status | Evidence |
 |---|---|---|