runward 0.13.3 → 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

@@ -68,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) {

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runward",
-  "version": "0.13.3",
+  "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/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.