runward 0.14.1 → 0.15.0

package/dist/lib/manifest-sync.js

@@ -0,0 +1,111 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseManifest, expectedRules, allRules } from "./conformance.js";
+import { RULE_MIGRATIONS } from "./rule-migrations.js";
+const SECTION_HEADER = /^##\s+Rule conformance/i;
+const SECTION_TEMPLATE = (phase) => `
+## Rule conformance
+
+> Account for every CRITICAL/HIGH craft rule mapped to the ${phase} phase (\`runward/rules/\`, frontmatter \`phases: [${phase}]\`). \`applied\` needs a pointer; \`deviated\` needs an ADR; \`n/a\` needs a reason. \`runward check --strict\` verifies this table.
+
+| Rule | Status | Evidence |
+|---|---|---|
+`;
+/** The slug a manifest table line carries, or null when the line is not a rule row. */
+function rowSlug(line) {
+    if (!line.trim().startsWith("|"))
+        return null;
+    const cols = line.split("|").slice(1, -1).map((c) => c.replace(/`/g, "").trim());
+    if (cols.length < 1)
+        return null;
+    const rule = cols[0];
+    if (/^rule$/i.test(rule) || /^:?-+:?$/.test(rule) || /^\[.*\]$/.test(rule))
+        return null;
+    return rule;
+}
+export function syncManifest(missionDir, phase, deliverable, label) {
+    const report = {
+        deliverable, label, fileMissing: false, sectionCreated: false,
+        added: [], migrated: [], removed: [], unknown: [], duplicates: [], content: null,
+    };
+    const path = join(missionDir, deliverable);
+    if (!existsSync(path)) {
+        report.fileMissing = true;
+        return report;
+    }
+    let content = readFileSync(path, "utf8");
+    const expected = expectedRules(missionDir, phase);
+    const known = new Set(allRules(missionDir));
+    // 1. Migrations (ADR-0006): rewrite a renamed slug in place, status and evidence untouched.
+    //    Skipped when the new slug already has its own row — that duplicate is the operator's edit.
+    const present = () => new Set(parseManifest(content).map((r) => r.rule));
+    for (const [from, m] of Object.entries(RULE_MIGRATIONS)) {
+        const rows = present();
+        if (!rows.has(from))
+            continue;
+        if (!m.to) {
+            report.removed.push({ slug: from, since: m.since, reason: m.reason });
+            continue;
+        }
+        if (rows.has(m.to)) {
+            report.duplicates.push(`${from} → ${m.to} (a ${m.to} row already exists — merge by hand)`);
+            continue;
+        }
+        content = content.split("\n").map((line) => {
+            const slug = rowSlug(line);
+            if (slug !== from)
+                return line;
+            const cols = line.split("|");
+            cols[1] = ` ${m.to} `;
+            return cols.join("|");
+        }).join("\n");
+        report.migrated.push({ from, to: m.to });
+    }
+    // 2. Section + missing rows, inside the manifest section only.
+    const lines = content.split("\n");
+    let start = lines.findIndex((l) => SECTION_HEADER.test(l));
+    if (start === -1 && expected.length > 0) {
+        if (!content.endsWith("\n"))
+            content += "\n";
+        content += SECTION_TEMPLATE(phase);
+        report.sectionCreated = true;
+    }
+    const rows = parseManifest(content).filter((r) => !/^\[.*\]$/.test(r.rule)); // template placeholders are form, not rows
+    const have = new Set(rows.map((r) => r.rule));
+    const counts = new Map();
+    for (const r of rows)
+        counts.set(r.rule, (counts.get(r.rule) ?? 0) + 1);
+    for (const [slug, n] of counts) {
+        if (n > 1)
+            report.duplicates.push(`${slug} (listed ${n} times — keep a single row)`);
+        if (!known.has(slug) && !RULE_MIGRATIONS[slug])
+            report.unknown.push(slug);
+    }
+    const missing = expected.filter((r) => !have.has(r));
+    if (missing.length > 0) {
+        const out = content.split("\n");
+        start = out.findIndex((l) => SECTION_HEADER.test(l));
+        // last table line of the section — append right below it, never reorder anything
+        let insertAt = -1;
+        for (let i = start + 1; i < out.length; i++) {
+            if (/^##\s/.test(out[i]))
+                break;
+            if (out[i].trim().startsWith("|"))
+                insertAt = i;
+        }
+        if (insertAt !== -1) {
+            out.splice(insertAt + 1, 0, ...missing.map((slug) => `| ${slug} |  |  |`));
+            report.added = missing;
+            // scaffolding real rows retires the template's placeholder row — form cleanup, no content touched
+            content = out.filter((l) => {
+                if (!l.trim().startsWith("|"))
+                    return true;
+                const first = l.split("|").slice(1, -1)[0]?.replace(/`/g, "").trim() ?? "";
+                return !/^\[.*\]$/.test(first);
+            }).join("\n");
+        }
+    }
+    const original = readFileSync(path, "utf8");
+    report.content = content !== original ? content : null;
+    return report;
+}

package/dist/lib/paths.js

@@ -7,6 +7,8 @@ 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");
+/** The reference floor the mission's manifests point at — shipped with it, so the evidence resolves (ADR-0019). */
+export const EXAMPLE_CODE = join(PKG_ROOT, "examples", "request-triage", "code");
 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/regimes.js

@@ -0,0 +1,32 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { PKG_ROOT } from "./paths.js";
+export const REGIMES_DIR = join(PKG_ROOT, "regimes");
+/** Shipped versions of a regime, ascending lexicographic. That order IS the contract: version
+ *  identifiers are chosen date-/zero-pad-shaped (2023, 2024-1689, 1.0) so lexicographic ==
+ *  chronological within a regime, and the default pick is the last element. */
+export function listRegimeVersions(regime, dir = REGIMES_DIR) {
+    if (!existsSync(dir))
+        return [];
+    const prefix = `${regime}@`;
+    return readdirSync(dir)
+        .filter((f) => f.startsWith(prefix) && f.endsWith(".json"))
+        .map((f) => f.slice(prefix.length, -".json".length))
+        .sort();
+}
+/** Load a regime mapping; default = highest shipped version. Throws with the shipped list on an
+ *  unknown version — the caller maps that onto exit 2 (operator misuse). */
+export function loadRegime(regime, version, dir = REGIMES_DIR) {
+    const versions = listRegimeVersions(regime, dir);
+    if (versions.length === 0)
+        throw new Error(`No shipped mapping data for regime "${regime}" (looked in ${dir}).`);
+    const pick = version ?? versions[versions.length - 1];
+    if (!versions.includes(pick)) {
+        throw new Error(`Unknown ${regime} mapping version "${version}". Shipped versions: ${versions.join(", ")}.`);
+    }
+    return JSON.parse(readFileSync(join(dir, `${regime}@${pick}.json`), "utf8"));
+}
+/** The lens identifier stamped into the draft header and the OSCAL props, e.g. "eu-ai-act@2024-1689". */
+export function regimeLensId(m) {
+    return `${m.regime}@${m.version}`;
+}

package/dist/lib/rules.js

@@ -0,0 +1,44 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { rulesDir } from "./conformance.js";
+import { TEMPLATES } from "./paths.js";
+const FRONTMATTER = /^---\n([\s\S]*?)\n---/;
+function listField(fm, key) {
+    const raw = fm.match(new RegExp(`^${key}:\\s*\\[(.*)\\]`, "m"))?.[1] ?? "";
+    return raw.split(",").map((s) => s.trim()).filter(Boolean);
+}
+export function parseRule(slug, content) {
+    const fm = content.match(FRONTMATTER)?.[1] ?? "";
+    const field = (key) => (fm.match(new RegExp(`^${key}:\\s*(.+)$`, "m"))?.[1] ?? "").trim();
+    return {
+        slug,
+        title: field("title") || slug,
+        impact: field("impact"),
+        phases: listField(fm, "phases"),
+        asi: listField(fm, "asi").map((s) => s.toUpperCase()).filter((s) => /^ASI\d{2}$/.test(s)),
+        tags: listField(fm, "tags"),
+        why: field("impactDescription"),
+        signature: field("signature") || null,
+    };
+}
+/** The rule body — everything after the frontmatter. */
+export function ruleBody(content) {
+    return content.replace(FRONTMATTER, "").replace(/^\n+/, "");
+}
+/** The effective rule set: the mission's copy when a mission is given and has one, else the package's. */
+export function ruleSetDir(missionDir) {
+    if (missionDir) {
+        const dir = rulesDir(missionDir);
+        return { dir, source: dir === join(TEMPLATES, "rules") ? "package" : "mission" };
+    }
+    return { dir: join(TEMPLATES, "rules"), source: "package" };
+}
+/** Deterministic inventory, sorted by slug. */
+export function readRuleSet(dir) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((f) => f.endsWith(".md"))
+        .sort()
+        .map((f) => parseRule(f.replace(/\.md$/, ""), readFileSync(join(dir, f), "utf8")));
+}

package/dist/lib/tools.js

@@ -41,7 +41,7 @@ const skillBody = (s) => [
     "",
     `Use this when ${s.when}.`,
     "",
-    `Confront the CRITICAL/HIGH craft rules mapped to the \`${s.phase}\` phase in \`runward/rules/\` — each rule's \`phases:\` frontmatter declares where it applies — at the point of action, not from memory. Account for each in the deliverable's \`## Rule conformance\` manifest: \`applied\` with a \`file:line\` or test, \`deviated\` with an ADR, or \`n/a\` with a reason.`,
+    `Confront the CRITICAL/HIGH craft rules mapped to the \`${s.phase}\` phase in \`runward/rules/\` — each rule's \`phases:\` frontmatter declares where it applies — at the point of action, not from memory (\`runward explain <rule>\` prints a rule's why and full text). Account for each in the deliverable's \`## Rule conformance\` manifest — \`runward manifest --sync\` scaffolds the missing rows; you fill the decision: \`applied\` with a typed pointer the gate verifies (\`file:PATH[:LINE][#SYMBOL]\`, \`test:PATH[::NAME]\`) or prose, \`deviated\` with an ADR, or \`n/a\` with a real reason. Signed rules (frontmatter \`signature:\`) need evidence whose content matches their signature.`,
     "",
     "This skill helps you *apply* the rules; it does not enforce them. `runward check --strict` is the sole authority and verifies the manifest deterministically. A rule surfaced here but not accounted for still fails the gate.",
     "",

package/dist/lib/verify-findings.js

@@ -0,0 +1,24 @@
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { GATED_DELIVERABLES } from "./conformance.js";
+/**
+ * The verify workflow's findings artifact (ADR-0007, amended): presence and freshness
+ * only — the gate never reads a verdict out of it and never blocks on it. Fresh means
+ * newer than every gated manifest; a manifest edited after the pass makes it stale.
+ */
+export const VERIFY_FINDINGS = "governance/verify-findings.md";
+export function verifyFindings(missionDir) {
+    const path = join(missionDir, VERIFY_FINDINGS);
+    if (!existsSync(path))
+        return { present: false };
+    const mtime = statSync(path).mtimeMs;
+    let fresh = true;
+    for (const { deliverable } of GATED_DELIVERABLES) {
+        const d = join(missionDir, deliverable);
+        if (existsSync(d) && statSync(d).mtimeMs > mtime) {
+            fresh = false;
+            break;
+        }
+    }
+    return { present: true, date: new Date(statSync(path).mtime).toISOString().slice(0, 10), fresh };
+}

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

@@ -0,0 +1,74 @@
+# Request triage — runnable floor
+
+The executable counterpart of the [request-triage example mission](../README.md).
+The mission documents in [`../runward/`](../runward/) decide; this code does
+exactly what they decided — nothing more. Standalone package, MIT, no key, no
+network: the default model adapter is a deterministic keyword classifier.
+
+## What the code shows
+
+- **Classification into a closed vocabulary** (`support`, `sales`,
+  `compliance`, `unknown`): the model proposes a category; anything outside
+  the vocabulary is treated as `unknown`. Abstention is a first-class answer:
+  an unknown category or a low confidence goes to the human review queue,
+  never to a plausible guess.
+- **Deterministic guard on extracted fields**
+  ([ADR-0002](../runward/adr/ADR-0002-deterministic-guard-on-extracted-fields.md)):
+  the model never supplies a value the system can compute or verify itself.
+  An account reference is resolved against a hard-coded registry — resolved
+  means `verified`, unresolved means the request escalates to review, it is
+  never routed on. A deadline is re-parsed from the source text by a
+  deterministic parser and the model's proposal is discarded, even when it
+  looks right.
+- **Guarded routing** (`RoutingPort`,
+  [contract](../runward/contracts/routing-port.md)): the system's only action
+  on the world. The adapter enforces the invariants itself: fail-closed
+  refusal of any record whose action-bearing fields are still
+  `model-proposed`, no compliance assignment without a recorded approval,
+  idempotency on the request id.
+- **Fail-closed compliance without a frozen process**: a compliance request
+  suspends — the validated record is serialized, the call returns
+  `suspended`, and `resumeTriage(requestId, "approve" | "reject", decidedBy)`
+  rehydrates it on the human decision. Approve routes with the approval
+  recorded; reject means the routing never happens. The summary the approver
+  sees is built by code from the validated fields, never a model
+  reformulation.
+
+## Quickstart
+
+Prerequisite: Node 20+.
+
+```bash
+npm install
+npm test     # 14 deterministic tests via node:test + tsx
+npm run demo # four requests end to end, including a compliance suspension
+```
+
+## Layout
+
+```
+code/
+  src/
+    core/
+      domain/triage.ts        # TriageRecord contract: categories, provenance markers, queues
+      domain/guard.ts         # deterministic guard: registry resolution, deadline re-parse, summary
+      ports/                  # model, account registry, routing, triage log
+      application/triage-request.usecase.ts  # orchestrate: propose -> guard -> route / suspend
+    adapters/
+      keyword-model.adapter.ts            # deterministic model (no key, no network)
+      hardcoded-account-registry.adapter.ts
+      in-memory-routing.adapter.ts        # enforces the routing invariants, fail-closed
+      in-memory-triage-log.adapter.ts
+    demo.ts
+  test/triage.test.ts
+```
+
+## Relation to the mission documents
+
+Same categories, same success criterion, same attached condition as the
+documents in [`../runward/`](../runward/): no compliance-category request is
+ever routed without human review — here that is a routing-port invariant the
+tests exercise, not a promise. The architecture note's ports
+([architecture.md §3](../runward/architecture.md)) map one to one onto
+`src/core/ports/`; the intake port is reduced to the validated input schema
+of the use case.

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

@@ -0,0 +1,19 @@
+{
+  "name": "runward-example-request-triage",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Runnable floor for the Runward request-triage example mission: classify inbound requests, extract key fields under a deterministic guard, route through a guarded port. Deterministic model adapter by default: no key, no network.",
+  "author": "Thibault Souris",
+  "license": "MIT",
+  "scripts": {
+    "test": "node --import tsx --test test/*.test.ts",
+    "demo": "node --import tsx src/demo.ts"
+  },
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.2"
+  }
+}

package/examples/request-triage/code/src/adapters/hardcoded-account-registry.adapter.ts

@@ -0,0 +1,23 @@
+// Account registry adapter: a small hard-coded table standing in for the
+// organization's system of record. The point is the contract, not the store:
+// the guard resolves references here, and a reference the registry does not
+// know is never routed on — however plausible the model made it look.
+
+import type {
+  AccountRegistryPort,
+  Account,
+} from "../core/ports/account-registry.port.js";
+
+const ACCOUNTS: readonly Account[] = [
+  { ref: "ACC-1001", name: "Acme Corp" },
+  { ref: "ACC-2002", name: "Globex Industries" },
+  { ref: "ACC-3003", name: "Initech Ltd" },
+];
+
+export class HardcodedAccountRegistry implements AccountRegistryPort {
+  private readonly byRef = new Map(ACCOUNTS.map((a) => [a.ref, a]));
+
+  resolve(ref: string): Account | null {
+    return this.byRef.get(ref) ?? null;
+  }
+}

package/examples/request-triage/code/src/adapters/in-memory-routing.adapter.ts

@@ -0,0 +1,79 @@
+// Routing adapter: in-memory stand-in for the ticketing anticorruption
+// adapter. It enforces the port's invariants itself — the guard is carried
+// by the boundary, not by the caller's discipline:
+//   - fail-closed on provenance: any action-bearing field still
+//     "model-proposed" is refused (ADR-0002);
+//   - a compliance record is never assigned without a recorded approval;
+//   - idempotent on requestId: assigning twice returns the same ticketRef.
+
+import type {
+  RoutingPort,
+  RoutingApproval,
+  RoutingConfirmation,
+} from "../core/ports/routing.port.js";
+import type { TriageRecord } from "../core/domain/triage.js";
+
+export class ProvenanceRefusalError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ProvenanceRefusalError";
+  }
+}
+
+export class ApprovalMissingError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ApprovalMissingError";
+  }
+}
+
+export class InMemoryRoutingAdapter implements RoutingPort {
+  private readonly tickets = new Map<string, RoutingConfirmation>();
+  private seq = 0;
+
+  // Test observability: how many assignments actually happened.
+  get assignments(): number {
+    return this.tickets.size;
+  }
+
+  async assign(
+    record: TriageRecord,
+    targetQueue: string,
+    approval?: RoutingApproval,
+  ): Promise<RoutingConfirmation> {
+    // Fail-closed on provenance: refuse, never repair.
+    const actionBearing = [record.accountRef, record.deadline].filter(
+      (f): f is NonNullable<typeof f> => f !== undefined,
+    );
+    const unverified = actionBearing.filter(
+      (f) => f.provenance === "model-proposed",
+    );
+    if (unverified.length > 0) {
+      throw new ProvenanceRefusalError(
+        `Refused (fail-closed): action-bearing field(s) still model-proposed: ${unverified
+          .map((f) => f.value)
+          .join(", ")}.`,
+      );
+    }
+
+    // A compliance record never routes without a recorded human approval.
+    if (record.category === "compliance" && !approval) {
+      throw new ApprovalMissingError(
+        `Refused (fail-closed): compliance record "${record.requestId}" has no recorded approval.`,
+      );
+    }
+
+    // Idempotent on requestId: no duplicate tickets.
+    const existing = this.tickets.get(record.requestId);
+    if (existing) return existing;
+
+    const confirmation: RoutingConfirmation = {
+      ticketRef: `TCK-${++this.seq}`,
+      routedAt: new Date().toISOString(),
+      queue: targetQueue,
+      approval,
+    };
+    this.tickets.set(record.requestId, confirmation);
+    return confirmation;
+  }
+}

package/examples/request-triage/code/src/adapters/in-memory-triage-log.adapter.ts

@@ -0,0 +1,42 @@
+// Persistence adapter: in-memory triage log. Append-only journal per request
+// id, plus the serialized suspension point of a record awaiting approval.
+
+import type {
+  TriageLogPort,
+  TriageLogEntry,
+  PendingRouting,
+} from "../core/ports/triage-log.port.js";
+
+export class InMemoryTriageLog implements TriageLogPort {
+  private readonly entries = new Map<string, TriageLogEntry[]>();
+  private readonly pending = new Map<string, PendingRouting>();
+
+  async append(requestId: string, entry: TriageLogEntry): Promise<void> {
+    const list = this.entries.get(requestId) ?? [];
+    list.push({ ...entry });
+    this.entries.set(requestId, list);
+  }
+
+  async read(requestId: string): Promise<TriageLogEntry[]> {
+    return (this.entries.get(requestId) ?? []).map((e) => ({ ...e }));
+  }
+
+  async setPending(requestId: string, pending: PendingRouting): Promise<void> {
+    if (this.pending.has(requestId)) {
+      throw new Error(`Request "${requestId}" is already suspended.`);
+    }
+    this.pending.set(requestId, {
+      ...pending,
+      record: structuredClone(pending.record),
+    });
+  }
+
+  async getPending(requestId: string): Promise<PendingRouting | null> {
+    const p = this.pending.get(requestId);
+    return p ? { ...p, record: structuredClone(p.record) } : null;
+  }
+
+  async clearPending(requestId: string): Promise<void> {
+    this.pending.delete(requestId);
+  }
+}

package/examples/request-triage/code/src/adapters/keyword-model.adapter.ts

@@ -0,0 +1,57 @@
+// Default model adapter: deterministic keyword classifier and extractor.
+// No key, no network, everything reproducible — the fallback classifier of
+// the mission's model-port contract, honoring the same contract as a real
+// model with lower recall. The adapter proposes; it never decides: every
+// value it emits is a hypothesis the deterministic guard will verify or
+// recompute (ADR-0002).
+
+import type {
+  TriageModelPort,
+  TriageProposal,
+  ProposedField,
+} from "../core/ports/model-provider.port.js";
+import type { Category } from "../core/domain/triage.js";
+
+// Order matters: compliance wins over support/sales when signals overlap —
+// a data-privacy request that also says "help" must surface as compliance
+// (a silent compliance miss is the one failure the mission forbids).
+const RULES: Array<{ category: Category; pattern: RegExp }> = [
+  {
+    category: "compliance",
+    pattern: /\b(gdpr|data (deletion|erasure|access)|privacy|regulator|dpo|right to be forgotten)\b/i,
+  },
+  {
+    category: "support",
+    pattern: /\b(crash(es|ed)?|error|bug|broken|fail(s|ed|ing)?|cannot|can't|not working|help)\b/i,
+  },
+  {
+    category: "sales",
+    pattern: /\b(pricing|quote|purchase|demo|upgrade|licen[sc]e|subscription|buy)\b/i,
+  },
+];
+
+const ACCOUNT_REF = /\bACC-\d{4}\b/;
+const ISO_DATE = /\b\d{4}-\d{2}-\d{2}\b/;
+
+export class KeywordModelAdapter implements TriageModelPort {
+  async propose(requestText: string): Promise<TriageProposal> {
+    const rule = RULES.find((r) => r.pattern.test(requestText));
+    const category: Category = rule?.category ?? "unknown";
+
+    const fields: ProposedField[] = [];
+    const ref = requestText.match(ACCOUNT_REF);
+    if (ref) {
+      fields.push({ name: "accountRef", value: ref[0], sourceSpan: ref[0] });
+    }
+    const date = requestText.match(ISO_DATE);
+    if (date) {
+      fields.push({ name: "deadline", value: date[0], sourceSpan: date[0] });
+    }
+
+    return {
+      category,
+      fields,
+      confidence: rule ? "high" : "low",
+    };
+  }
+}