runward 0.13.2 → 0.14.0

package/README.md

@@ -6,7 +6,7 @@
 
 **After the spec, the hard part starts. Runward ships it and runs it.**
 
-*Run-grade engineering for agentic systems — from business need to a system that holds in production.*
+*The floor that keeps an agentic system alive. Run-grade engineering, from business need to production.*
 
 Your agent builds fast. Runward frames what it builds — six gated phases your agent executes and one human signs off — so what ships actually holds.
 

package/dist/cli.js

@@ -13,7 +13,8 @@ import { doctorCommand } from "./commands/doctor.js";
 import { updateCommand } from "./commands/update.js";
 import { characterizeCommand } from "./commands/characterize.js";
 import { complianceCommand } from "./commands/compliance.js";
-// Exit codes: 0 = success · 1 = gaps/warnings · 2 = missing prerequisite
+import { TOOL_IDS } from "./lib/tools.js";
+// Exit codes: 0 = success · 1 = gaps/warnings · 2 = missing prerequisite or CLI misuse (typo, unknown flag)
 process.on("uncaughtException", (err) => {
     if (err.name === "ExitPromptError")
         process.exit(130); // Ctrl+C in a prompt
@@ -52,7 +53,7 @@ program
     .command("init")
     .description("scaffold the mission structure (interactive wizard, or --yes)")
     .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("-t, --tools <list>", `comma-separated tool profiles: ${TOOL_IDS.join(",")}`)
     .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);
@@ -91,4 +92,27 @@ program
     .argument("[regime]", "iso-42001 | nist-ai-rmf | eu-ai-act")
     .option("-p, --path <path>", "project directory")
     .action(complianceCommand);
-program.parseAsync();
+// exitOverride lets us map Commander's own errors onto runward's exit-code contract:
+// a parse error (unknown command/option, missing/excess argument) is operator misuse → 2,
+// so CI can tell a typo from a legitimate gate failure (exit 1). Help/version exit 0.
+// Applied to the root AND every subcommand — it does not propagate on its own.
+const MISUSE = new Set([
+    "commander.unknownCommand", "commander.unknownOption", "commander.invalidArgument",
+    "commander.missingArgument", "commander.excessArguments",
+    "commander.missingMandatoryOptionValue", "commander.optionMissingArgument",
+]);
+const onCommanderExit = (err) => {
+    const code = err?.code ?? "";
+    if (code === "commander.helpDisplayed" || code === "commander.version" || code === "commander.help")
+        process.exit(0);
+    process.exit(MISUSE.has(code) ? 2 : (err?.exitCode ?? 1)); // Commander already wrote the message
+};
+program.exitOverride(onCommanderExit);
+program.commands.forEach((cmd) => cmd.exitOverride(onCommanderExit));
+program.parseAsync().catch((err) => {
+    // An error escaping an async action — Commander's own exits are handled above.
+    console.error("\n  " + c.error("✗") + " " + (err?.message ?? String(err)));
+    if (process.env.VERBOSE && err?.stack)
+        console.error(err.stack);
+    process.exit(1);
+});

package/dist/commands/check.js

@@ -1,6 +1,7 @@
 import { join, resolve } from "node:path";
 import { analyze, findMissionRoot } from "../lib/mission.js";
 import { conformance, driftReport, unratifiedAdrs, decisionCoverage } from "../lib/conformance.js";
+import { behavioralProof } from "../lib/behavioral-proof.js";
 import { runHooks } from "../lib/hooks.js";
 import { c, createHeader, section, status } from "../lib/styles.js";
 import { VERSION } from "../lib/paths.js";
@@ -67,7 +68,10 @@ export async function checkCommand(opts) {
             for (const d of driftReport(mission, deliverable))
                 drift.push(`${label} · ${d.rule} — ${d.problem}`);
             const { expected, violations } = conformance(mission, phase, deliverable);
-            if (expected.length === 0)
+            // Non-vacuity (ADR-0002): when no rules are currently mapped to a phase, conformance()
+            // still raises a `(mapping)` violation if the mapping was stripped below its pinned
+            // floor. Only skip when there is genuinely nothing to report — never discard that signal.
+            if (expected.length === 0 && violations.length === 0)
                 continue;
             checked++;
             if (violations.length === 0) {
@@ -96,6 +100,27 @@ export async function checkCommand(opts) {
             strictGaps += unratified.length;
         }
         if (checked > 0 && strictGaps === 0) {
+            // The two proofs, made legible together: this gate is the DOCUMENTARY proof (decisions traced);
+            // the BEHAVIORAL proof is the operator's test suite. runward reads the pointer, never runs the code.
+            console.log(section("Behavioral proof (advisory, above the gate)"));
+            console.log("  " + c.darkGray("this gate is the documentary proof: the decisions are traced. runward did not run your code — it is not a runtime. The behavioral proof is your test suite."));
+            const bp = behavioralProof(mission, root);
+            if (!bp.declared) {
+                console.log("  " + c.darkGray("no behavioral proof declared — add `Behavioral proof: <command>` to runward/floor.md §2 (and optionally `Proof artifact: <path>`)."));
+            }
+            else {
+                if (bp.command)
+                    console.log(`  ${c.darkGray("prove behavior with:")} ${c.white(bp.command)}`);
+                if (bp.artifact) {
+                    if (!bp.present)
+                        console.log(`  ${c.warning("◑")} ${c.darkGray("proof artifact")} ${c.white(bp.artifact)} ${c.warning("missing — run the command to produce it")}`);
+                    else {
+                        const fresh = bp.fresh === undefined ? "" : bp.fresh ? c.success(" · fresh") : c.warning(" · stale (older than the code — re-run)");
+                        console.log(`  ${c.success("✓")} ${c.darkGray("proof artifact")} ${c.white(bp.artifact)} ${c.darkGray(`(${bp.date})`)}${fresh}`);
+                    }
+                }
+                console.log("  " + c.darkGray("advisory — runward reports presence and freshness, never runs or reads the result. You cross on both proofs."));
+            }
             console.log(section("Semantic check (advisory, above the gate)"));
             console.log("  " + c.darkGray("the gate proved every CRITICAL/HIGH rule was traced — not that the code applies it. Before you cross, run the verify workflow (runward/workflows/verify.md): an adversarial cite-vs-apply pass, ideally on a different model. Advisory, agent-executed, never blocks the gate (ADR-0007)."));
         }

package/dist/commands/status.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { analyze, findMissionRoot } from "../lib/mission.js";
+import { analyze, findMissionRoot, isRealAdr } from "../lib/mission.js";
 import { c, createHeader, section } from "../lib/styles.js";
 import { VERSION, WORKFLOWS } from "../lib/paths.js";
 /** Mission snapshot: phase progress, decision journal, activity, workflows —
@@ -44,7 +44,7 @@ export async function statusCommand(opts) {
     console.log(section("Decision journal"));
     const adrDir = join(mission, "adr");
     const adrs = existsSync(adrDir)
-        ? readdirSync(adrDir).filter((f) => /^ADR-\d+/.test(f) && !f.includes("0000")).sort()
+        ? readdirSync(adrDir).filter(isRealAdr).sort()
         : [];
     if (adrs.length === 0) {
         console.log(c.darkGray("  no ADR yet — every structural decision must be locked"));

package/dist/lib/behavioral-proof.js

@@ -0,0 +1,46 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+export function behavioralProof(mission, root) {
+    const floor = join(mission, "floor.md");
+    if (!existsSync(floor))
+        return { declared: false };
+    const text = readFileSync(floor, "utf8");
+    const cmd = text.match(/^\s*[*_]*Behavioral proof[*_]*\s*:\s*`?([^`\n]+?)`?\s*$/mi);
+    const art = text.match(/^\s*[*_]*Proof artifact[*_]*\s*:\s*`?([^`\n]+?)`?\s*$/mi);
+    if (!cmd && !art)
+        return { declared: false };
+    const proof = { declared: true, command: cmd?.[1]?.trim(), artifact: art?.[1]?.trim() };
+    if (proof.artifact) {
+        const abs = join(root, proof.artifact);
+        proof.present = existsSync(abs);
+        if (proof.present) {
+            const st = statSync(abs);
+            proof.date = st.mtime.toISOString().slice(0, 10);
+            const codeDir = join(root, "code");
+            const newest = existsSync(codeDir) ? newestSourceMtime(codeDir) : 0;
+            proof.fresh = newest === 0 ? undefined : st.mtimeMs >= newest;
+        }
+    }
+    return proof;
+}
+/** Newest mtime of a tracked source file under a dir — read-only, node_modules and dotfiles skipped. */
+function newestSourceMtime(dir) {
+    let newest = 0;
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return 0;
+    }
+    for (const e of entries) {
+        if (e.name === "node_modules" || e.name.startsWith("."))
+            continue;
+        const p = join(dir, e.name);
+        if (e.isDirectory())
+            newest = Math.max(newest, newestSourceMtime(p));
+        else if (/\.(ts|tsx|js|jsx|py|go|rs|java|rb)$/.test(e.name))
+            newest = Math.max(newest, statSync(p).mtimeMs);
+    }
+    return newest;
+}

package/dist/lib/conformance.js

@@ -59,7 +59,9 @@ export function parseManifest(content) {
         const cols = line.split("|").slice(1, -1).map((c) => c.replace(/`/g, "").trim());
         if (cols.length < 3)
             continue;
-        const [rule, status, evidence] = cols;
+        // Evidence may itself contain a pipe (a TS union `a | b`, a table hint) — rejoin the
+        // tail so it is not truncated, which would wrongly fail an n/a row on a trivial reason.
+        const rule = cols[0], status = cols[1], evidence = cols.slice(2).join(" | ");
         if (/^rule$/i.test(rule) || /^:?-+:?$/.test(rule))
             continue; // header / separator
         rows.push({ rule, status: status.toLowerCase(), evidence });
@@ -71,7 +73,12 @@ function adrExists(missionDir, evidence) {
     if (!id)
         return false;
     const dir = join(missionDir, "adr");
-    return existsSync(dir) && readdirSync(dir).some((f) => f.toUpperCase().startsWith(id));
+    // Anchor on a digit boundary so a `deviated` row citing ADR-1 is not satisfied by
+    // ADR-10 / ADR-12 when filenames are unpadded.
+    return existsSync(dir) && readdirSync(dir).some((f) => {
+        const u = f.toUpperCase();
+        return u.startsWith(id) && !/[0-9]/.test(u.charAt(id.length));
+    });
 }
 /**
  * The reconstruction lifecycle (ADR-0013/0014). A retroactively reconstructed decision is a

package/dist/lib/mission.js

@@ -54,13 +54,19 @@ export function findMissionRoot(cwd) {
 // which distinguishes it from cross-references like [ADR-0001] or [framing.md].
 // A closing bracket followed by "(" is a markdown link ([floor note](floor.md)) — never a placeholder.
 const PLACEHOLDER = /\[[^\]\n]*\s[^\]\n]{1,80}\](?!\()/g;
+/** A real ADR file: ADR-<n>-*.md, excluding the scaffolded template. Single source of
+ *  truth so the mission, status, and conformance paths agree (they used to diverge:
+ *  a `!f.includes("0000")` filter wrongly dropped e.g. ADR-0021-…-10000-ms.md). */
+export function isRealAdr(f) {
+    return /^ADR-\d+/.test(f) && f.endsWith(".md") && f !== "ADR-0000-template.md";
+}
 export function artifactState(missionDir, a) {
     const path = join(missionDir, a.relPath);
     if (!existsSync(path))
         return "missing";
     // Special case: ADR directory — count real ADRs beyond the template.
     if (a.relPath === "adr") {
-        const adrs = readdirSync(path).filter((f) => /^ADR-\d+/.test(f) && !f.includes("0000"));
+        const adrs = readdirSync(path).filter(isRealAdr);
         return adrs.length > 0 ? "filled" : "untouched";
     }
     // Special case: contracts directory — filled as soon as one .md is not the raw port-contract template.
@@ -77,9 +83,22 @@ export function artifactState(missionDir, a) {
         const template = readFileSync(join(TEMPLATES, "mission", a.templateKey), "utf8");
         if (content.trim() === template.trim())
             return "untouched";
+        if ((content.match(PLACEHOLDER) || []).length >= 3)
+            return "in-progress";
+        // Divergence guard: a deliverable is "filled" only when it departs meaningfully from
+        // the scaffold. Templates with few placeholders (decision-matrix, execution-topology)
+        // cannot lean on the placeholder floor, so a one-byte interior edit would otherwise
+        // pass. Require several lines of genuinely new content beyond the template. Calibrated
+        // against the reference mission (its lightest fill adds 5 lines / 215 words).
+        const lines = (s) => s.split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
+        const templateLines = new Set(lines(template));
+        const added = lines(content).filter((l) => !templateLines.has(l));
+        const addedWords = added.reduce((n, l) => n + l.split(/\s+/).filter(Boolean).length, 0);
+        if (added.length < 3 || addedWords < 20)
+            return "in-progress";
+        return "filled";
     }
-    const placeholders = (content.match(PLACEHOLDER) || []).length;
-    if (placeholders >= 3)
+    if ((content.match(PLACEHOLDER) || []).length >= 3)
         return "in-progress";
     return "filled";
 }
@@ -90,7 +109,7 @@ export function analyze(missionDir) {
     });
     const adrDir = join(missionDir, "adr");
     const adrCount = existsSync(adrDir)
-        ? readdirSync(adrDir).filter((f) => /^ADR-\d+/.test(f) && !f.includes("0000")).length
+        ? readdirSync(adrDir).filter(isRealAdr).length
         : 0;
     const firstIncomplete = phases.find((p) => !p.complete);
     return { phases, adrCount, currentPhase: firstIncomplete ? firstIncomplete.spec.label : "all gates passed" };

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

@@ -37,6 +37,10 @@
 - **Verdict**: criterion met on the replayed sample and the first live week. The gate to `iterate` requires the full two-week live window per the criterion's wording — one more week of live measurement before the gate is crossed. Partial by duration, not by result.
 - **Observability check**: confirmed — a full trajectory (intake, model proposal, per-field guard outcome, routing decision, persistence) reconstructs from a single request ID; verified on 10 randomly drawn requests.
 
+**Behavioral proof**: `cd code && npm test`
+
+> 14 deterministic tests, no key, no network — including the guard refusing, fail-closed, a record whose action-bearing fields are still model-proposed (ADR-0002). The gate above proves the *decision* to guard was traced; this proves the guard *runs*. runward reports the pointer, never runs it.
+
 ## 3. Gaps and deviations
 
 | Gap / deviation | Impact | Agreed with sponsor |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runward",
-  "version": "0.13.2",
+  "version": "0.14.0",
   "description": "After the spec: ship and run. A delivery framework for agentic systems — floor first, evolution on evidence, governance from day zero, handover with proof.",
   "keywords": [
     "agentic",

package/templates/mission/floor.md

@@ -34,6 +34,11 @@
 - **Verdict**: [criterion met / partially met / not met — and what that means for the gate.]
 - **Observability check**: [confirmation that a full trajectory reconstructs from a single request ID.]
 
+**Behavioral proof**: `[the command that proves the floor's behavior, e.g. cd code && npm test]`
+**Proof artifact**: [optional — a result file the command writes, e.g. code/test-results.json; runward reports it present/fresh, never runs or reads it]
+
+> The gate above is the *documentary* proof (the decisions are traced). This line is the *behavioral* proof (your code actually runs). runward never executes it — it is not a runtime; on a green `--strict` it only reports the pointer, and the artifact's presence and freshness if you name one.
+
 ## 3. Gaps and deviations
 
 [Anything shipped differently from the architecture note, and anything the measurement revealed. Deviations were agreed with the sponsor, never silent.]

package/templates/workflows/architect.md

@@ -8,12 +8,14 @@ Use this workflow once framing is decided and structure must follow: "how do we
 
 - The framing note: floor/target split, success criterion, hard constraints, presumed boundaries.
 - The `mission/architecture.md`, `mission/port-contract.md`, and `mission/adr/ADR-0000-template.md` templates.
+- The `mission/decision-matrix.md` template (the structuring defaults and the trigger that switches each).
 - The `mission/shared-bricks.md` and `mission/execution-topology.md` templates (the infrastructure vision).
 
 ## Outputs
 
 - A light architecture note.
 - The port list with contracts and the integration protocol.
+- The decision matrix adopted for the mission: each structuring choice with its sober default and the objective trigger that switches it (`mission/decision-matrix.md`).
 - The execution-topology note: each port placed behind its location family, with data class and sovereignty.
 - One ADR per structuring decision, including each non-in-app placement.
 
@@ -41,6 +43,7 @@ Use this workflow once framing is decided and structure must follow: "how do we
 ## Definition of Done
 
 - Architecture note produced, boundaries first, stack open.
+- Decision matrix adopted for the mission: every structuring choice carries a sober default and an objective trigger; the positions taken so far are recorded (`mission/decision-matrix.md`).
 - Every port named with contract and initial version; integration protocol stated.
 - Execution-topology note produced: every port placed behind a location family, with its data class(es) and sovereignty; non-in-app placements carry an ADR; the usage registry is seeded.
 - One ADR per structuring choice, locked before the note mentions it.

package/templates/workflows/frame.md

@@ -13,6 +13,7 @@ Use this workflow at the start of any agentic-system mission, or whenever the pe
 ## Outputs
 
 - A framing note (use the `mission/framing.md` template).
+- A steering contract (use the `mission/mission-contract.md` template): what is delivered, on what condition it is accepted, and along which roadmap — filled with the sponsor, tying the success criterion to the deliverables and the milestones.
 - The floor/target split with named deferrals.
 - Presumed architecture boundaries — ports and integration protocol, stack left open.
 
@@ -55,6 +56,7 @@ Lock any truly structuring decision through `decision-loop` before committing it
 ## Definition of Done
 
 - Framing note produced: problem, value, observable success criterion, hard constraints — one page.
+- Steering contract filled with the sponsor: the success criterion tied to the deliverables and to what closes each engagement (`mission/mission-contract.md`).
 - Floor perimeter listed, every deferral named with its trigger.
 - Presumed boundaries stated; language and topology explicitly left open.
 - Note reviewed via `review` before circulation.