runward 0.7.0 → 0.8.0

package/README.md

@@ -8,7 +8,7 @@ Your agent builds fast. Runward frames what it builds — six gated phases your
 
 Runward is a delivery framework for agentic systems. It covers the entire mission, from framing to handover — it opens before any spec in greenfield, or picks up where the spec tools stop, and carries through to the run and the handover either way. Three ways in: day one of a new project (Frame is the first gate, before any spec exists), from an existing spec (Spec Kit, OpenSpec or in-house — it becomes the input of framing), or from an existing prototype (brownfield: characterize before touching anything). Then: floor first (the floor: the smallest *running* system that proves value on real traffic), evolution on evidence, governance from day zero, and a handover that makes your team autonomous.
 
-> Spec Kit, OpenSpec and BMAD stop at authoring: specs, plans, implementation. Runward pilots the whole mission — and picks up their output if you use them. What none of them *structures* is the run: governed memory, resilience, execution security, continuous evaluation, transmission.
+> Spec Kit, OpenSpec and BMAD take you to tested, sometimes merged code. Runward pilots the whole mission — and picks up their output if you use them. What none of them *structures* is the run: governed memory, resilience, execution security, continuous evaluation, transmission.
 
 ## Why
 

package/dist/cli.js

@@ -58,6 +58,7 @@ program
     .description("can I cross the gate — gate audit, exit 1 on gaps (CI-friendly)")
     .option("-p, --path <path>", "project directory")
     .option("--strict", "also verify the floor rule-conformance manifest (deterministic)")
+    .option("--hooks", "run operator hooks from runward/hooks.json around the audit (opt-in)")
     .action(checkCommand);
 program
     .command("status")

package/dist/commands/check.js

@@ -1,6 +1,7 @@
 import { join } from "node:path";
 import { analyze, findMissionRoot } from "../lib/mission.js";
-import { conformance } from "../lib/conformance.js";
+import { conformance, driftReport } from "../lib/conformance.js";
+import { runHooks } from "../lib/hooks.js";
 import { c, createHeader, section, status } from "../lib/styles.js";
 import { VERSION } from "../lib/paths.js";
 /**
@@ -21,6 +22,15 @@ export async function checkCommand(opts) {
     const mission = join(root, "runward");
     const report = analyze(mission);
     console.log(createHeader(`Runward v${VERSION} — gate audit`, root));
+    let hookFailed = 0;
+    if (opts.hooks) {
+        const before = runHooks(mission, "before", root);
+        if (before.ran > 0) {
+            console.log(section("Hooks · before"));
+            console.log("  " + (before.failed.length ? status.error(`${before.failed.length}/${before.ran} failed`) : status.success(`${before.ran} ok`)));
+            hookFailed += before.failed.length;
+        }
+    }
     const glyph = {
         "filled": c.success("✓"),
         "in-progress": c.warning("◐"),
@@ -51,7 +61,10 @@ export async function checkCommand(opts) {
         ];
         console.log(section("Rule conformance (--strict)"));
         let checked = 0;
+        const drift = [];
         for (const { phase, deliverable, label } of CONFORMANCE) {
+            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)
                 continue;
@@ -67,11 +80,25 @@ export async function checkCommand(opts) {
         }
         if (checked === 0)
             console.log("  " + c.darkGray("no CRITICAL/HIGH rules mapped to a build phase"));
+        if (drift.length > 0) {
+            console.log(section("Drift (advisory)"));
+            for (const d of drift)
+                console.log(`  ${c.warning("◑")} ${c.white(d)}`);
+            console.log("  " + c.darkGray("advisory — an applied pointer no longer resolves; verify it. Does not fail the gate."));
+        }
+    }
+    if (opts.hooks) {
+        const after = runHooks(mission, "after", root);
+        if (after.ran > 0) {
+            console.log(section("Hooks · after"));
+            console.log("  " + (after.failed.length ? status.error(`${after.failed.length}/${after.ran} failed`) : status.success(`${after.ran} ok`)));
+            hookFailed += after.failed.length;
+        }
     }
     console.log(section("Summary"));
     console.log(`  ${c.primaryBold("Current gate")}  ${c.white(report.currentPhase)}`);
     console.log(`  ${c.primaryBold("ADRs")}          ${c.white(String(report.adrCount))}${report.adrCount === 0 ? c.warning("  — no structural decision locked yet") : ""}`);
-    if (gaps === 0 && strictGaps === 0) {
+    if (gaps === 0 && strictGaps === 0 && hookFailed === 0) {
         console.log("\n" + status.success("All expected deliverables are filled. Cross gates on evidence, not on paperwork."));
     }
     else {
@@ -80,6 +107,8 @@ export async function checkCommand(opts) {
             parts.push(`${gaps} deliverable(s) not filled`);
         if (strictGaps)
             parts.push(`${strictGaps} floor rule-conformance gap(s)`);
+        if (hookFailed)
+            parts.push(`${hookFailed} hook(s) failed`);
         console.log("\n" + status.warning(`${parts.join(" · ")}. No phase closes without its artifact — and, under --strict, without its CRITICAL/HIGH rules accounted for.`));
         process.exitCode = 1;
     }

package/dist/commands/doctor.js

@@ -2,7 +2,8 @@ import { execFileSync } from "node:child_process";
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { TEMPLATES, MISSION_LAYOUT, VERSION, WORKFLOWS } from "../lib/paths.js";
-import { EXPECTED_RULES } from "../lib/constants.js";
+import { EXPECTED_RULES, EXPECTED_MAPPED } from "../lib/constants.js";
+import { expectedRules } from "../lib/conformance.js";
 import { findMissionRoot } from "../lib/mission.js";
 import { createHeader, section, status } from "../lib/styles.js";
 /**
@@ -34,6 +35,11 @@ export async function doctorCommand() {
     const rulesDir = join(TEMPLATES, "rules");
     const ruleCount = existsSync(rulesDir) ? readdirSync(rulesDir).filter((f) => f.endsWith(".md")).length : 0;
     ruleCount === EXPECTED_RULES ? ok(`${ruleCount} craft rules`) : fail(`craft rules mismatch: ${ruleCount}/${EXPECTED_RULES}`);
+    // Routed-count floor (ADR-0002): the phases: mapping must not be stripped below its pinned minimum.
+    const belowFloor = Object.entries(EXPECTED_MAPPED).filter(([phase, floor]) => expectedRules(TEMPLATES, phase).length < floor);
+    belowFloor.length === 0
+        ? ok(`rule mapping floors met (${Object.entries(EXPECTED_MAPPED).map(([p, f]) => `${p}≥${f}`).join(", ")})`)
+        : fail(`rule mapping below floor: ${belowFloor.map(([p, f]) => `${p} ${expectedRules(TEMPLATES, p).length}/${f}`).join(", ")}`);
     console.log(section("Current directory"));
     const root = findMissionRoot(process.cwd());
     if (!root) {

package/dist/lib/conformance.js

@@ -1,8 +1,15 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { join } from "node:path";
+import { join, dirname } from "node:path";
 import { TEMPLATES } from "./paths.js";
+import { EXPECTED_MAPPED } from "./constants.js";
+import { RULE_MIGRATIONS } from "./rule-migrations.js";
 const FRONTMATTER = /^---\n([\s\S]*?)\n---/;
 const VALID_STATUS = new Set(["applied", "deviated", "n/a"]);
+/** An n/a reason must be more than a placeholder: real length, not a bracketed template token. */
+function trivialReason(s) {
+    const t = s.trim();
+    return t.length < 8 || /^\[.*\]$/.test(t);
+}
 function parseRuleMeta(content) {
     const fm = content.match(FRONTMATTER)?.[1] ?? "";
     const impact = (fm.match(/^impact:\s*(.+)$/m)?.[1] ?? "").trim();
@@ -28,6 +35,14 @@ export function expectedRules(missionDir, phaseId) {
         .map((f) => f.replace(/\.md$/, ""))
         .sort();
 }
+/** Every rule slug in the set (mission's own, else the package) — the universe a manifest row must belong to. */
+export function allRules(missionDir) {
+    const missionRules = join(missionDir, "rules");
+    const dir = existsSync(missionRules) ? missionRules : join(TEMPLATES, "rules");
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir).filter((f) => f.endsWith(".md")).map((f) => f.replace(/\.md$/, ""));
+}
 /** Parse the "## Rule conformance" markdown table from a deliverable. */
 export function parseManifest(content) {
     const lines = content.split("\n");
@@ -58,19 +73,65 @@ function adrExists(missionDir, evidence) {
     const dir = join(missionDir, "adr");
     return existsSync(dir) && readdirSync(dir).some((f) => f.toUpperCase().startsWith(id));
 }
+// A path token: a file with a known code/doc extension (excludes version numbers like v1.0, "§2").
+const PATH_TOKEN = /[\w./-]+\.(?:ts|tsx|js|jsx|mjs|cjs|py|md|json|ya?ml|toml|go|rs|java|rb|php|sql|sh|css|scss|html|txt)\b/g;
+/** Advisory drift (ADR-0004): applied pointers whose file path no longer resolves. Existence only. */
+export function driftReport(missionDir, deliverable) {
+    const path = join(missionDir, deliverable);
+    if (!existsSync(path))
+        return [];
+    const bases = [dirname(missionDir), missionDir, dirname(path)];
+    const out = [];
+    for (const row of parseManifest(readFileSync(path, "utf8"))) {
+        if (row.status !== "applied")
+            continue;
+        const tokens = row.evidence.match(PATH_TOKEN) ?? [];
+        if (tokens.length === 0)
+            continue; // pure prose reference — the operator's judgment
+        const resolves = tokens.some((t) => bases.some((b) => existsSync(join(b, t))));
+        if (!resolves)
+            out.push({ rule: row.rule, problem: `applied pointer does not resolve (drift?): ${row.evidence} — update the pointer or remove the row` });
+    }
+    return out;
+}
 /** Verify a build phase's conformance manifest against its expected rule set. */
 export function conformance(missionDir, phaseId, deliverable) {
     const expected = expectedRules(missionDir, phaseId);
     const violations = [];
+    // Non-vacuity (ADR-0002): the mapping cannot be stripped below its pinned floor.
+    const floor = EXPECTED_MAPPED[phaseId];
+    if (floor !== undefined && expected.length < floor) {
+        violations.push({ rule: "(mapping)", problem: `only ${expected.length} CRITICAL/HIGH rules mapped to '${phaseId}', floor is ${floor} — the mapping may have been stripped; restore the phases: [...] frontmatter on this phase's rules` });
+    }
     const path = join(missionDir, deliverable);
     if (!existsSync(path)) {
         return { expected, violations: expected.map((rule) => ({ rule, problem: `${deliverable} missing` })) };
     }
-    const byRule = new Map(parseManifest(readFileSync(path, "utf8")).map((r) => [r.rule, r]));
+    const rows = parseManifest(readFileSync(path, "utf8"));
+    // Form-lint (ADR-0003): well-formedness before the semantic check. Skip template placeholder tokens.
+    const known = new Set(allRules(missionDir));
+    const counts = new Map();
+    for (const r of rows) {
+        if (/^\[.*\]$/.test(r.rule))
+            continue;
+        counts.set(r.rule, (counts.get(r.rule) ?? 0) + 1);
+    }
+    for (const [rule, n] of counts) {
+        if (!known.has(rule)) {
+            const m = RULE_MIGRATIONS[rule];
+            const hint = m
+                ? (m.to ? ` — renamed to '${m.to}' in ${m.since} (${m.reason})` : ` — removed in ${m.since} (${m.reason})`)
+                : " (typo? not in runward/rules/)";
+            violations.push({ rule, problem: `unknown rule${hint}` });
+        }
+        if (n > 1)
+            violations.push({ rule, problem: `listed ${n} times in the manifest — keep a single row per rule` });
+    }
+    const byRule = new Map(rows.map((r) => [r.rule, r]));
     for (const rule of expected) {
         const row = byRule.get(rule);
         if (!row) {
-            violations.push({ rule, problem: "not accounted for in the Rule conformance manifest" });
+            violations.push({ rule, problem: "not accounted for in the Rule conformance manifest — add a row: applied with a file:line/test, deviated with an ADR, or n/a with a reason" });
             continue;
         }
         if (!VALID_STATUS.has(row.status)) {
@@ -78,11 +139,11 @@ export function conformance(missionDir, phaseId, deliverable) {
             continue;
         }
         if (row.status === "applied" && !row.evidence)
-            violations.push({ rule, problem: "applied without an evidence pointer" });
+            violations.push({ rule, problem: "applied without an evidence pointer — put a file:line or a test in the Evidence column" });
         if (row.status === "deviated" && !adrExists(missionDir, row.evidence))
-            violations.push({ rule, problem: "deviated but no matching ADR in runward/adr/" });
-        if (row.status === "n/a" && !row.evidence)
-            violations.push({ rule, problem: "n/a without a reason" });
+            violations.push({ rule, problem: "deviated but no matching ADR in runward/adr/ — reference an ADR that exists there" });
+        if (row.status === "n/a" && trivialReason(row.evidence))
+            violations.push({ rule, problem: "n/a with an empty or placeholder reason — give a real one-line reason why it does not apply here" });
     }
     return { expected, violations };
 }

package/dist/lib/constants.js

@@ -1,2 +1,6 @@
 /** Total number of craft rules shipped under templates/rules/. */
 export const EXPECTED_RULES = 51;
+/** Routed-count floor: minimum CRITICAL/HIGH rules mapped to each build phase (ADR-0002).
+ *  Lowering a floor is a deliberate, tracked edit — the `phases:` mapping cannot be silently
+ *  stripped to make `check --strict` pass vacuously. */
+export const EXPECTED_MAPPED = { architect: 5, floor: 10, govern: 7 };

package/dist/lib/hooks.js

@@ -0,0 +1,26 @@
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+export function runHooks(missionDir, phase, cwd) {
+    const result = { ran: 0, failed: [] };
+    const path = join(missionDir, "hooks.json");
+    if (!existsSync(path))
+        return result;
+    let cfg;
+    try {
+        cfg = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return result;
+    }
+    for (const cmd of cfg[phase] ?? []) {
+        result.ran++;
+        try {
+            execSync(cmd, { cwd, stdio: "inherit" });
+        }
+        catch {
+            result.failed.push(cmd);
+        }
+    }
+    return result;
+}

package/dist/lib/paths.js

@@ -24,5 +24,5 @@ export const MISSION_LAYOUT = {
 };
 export const WORKFLOWS = [
     "method", "frame", "architect", "floor", "iterate",
-    "govern", "handover", "brownfield", "review", "decision-loop",
+    "govern", "handover", "brownfield", "review", "decision-loop", "verify",
 ];

package/dist/lib/rule-migrations.js

@@ -0,0 +1,7 @@
+export const RULE_MIGRATIONS = {
+    "hexa-llm-boundary-principle": {
+        to: "hexa-move-deterministic-out",
+        reason: "the name is reserved for the founding inversion",
+        since: "v0.7.0",
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runward",
-  "version": "0.7.0",
+  "version": "0.8.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", "ai-agents", "spec-driven", "delivery", "governance", "llm", "architecture"],
   "author": "Thibault Souris",

package/templates/workflows/verify.md

@@ -0,0 +1,33 @@
+# Verify — Advisory Cite-vs-Apply Review (above the gate, never in it)
+
+## When to use
+
+Use this **after** `runward check --strict` is green, and before you cross the gate as the operator. The deterministic gate proves a decision was *traced* for every CRITICAL/HIGH rule (applied with a pointer, deviated with an ADR, n/a with a reason). It cannot prove the code an `applied` row points at **actually applies** the rule rather than merely citing it — that is a semantic judgment. This workflow makes that judgment, adversarially, to inform yours.
+
+It is **advisory**. It produces findings, never a verdict that gates. `runward check --strict` stays the load-bearing decision; you cross it. See [ADR-0007].
+
+## Inputs
+
+- The `Rule conformance` manifests (`floor.md`, `architecture.md`, `governance/threat-model.md`).
+- The code each `applied` row points at.
+
+## Procedure
+
+**Challenge each `applied` claim, adversarially.** For every `applied` row, open its evidence (the `file:line` or test) and default to skepticism: *does this code actually apply the rule it names, or does it only cite it?* Judge through distinct lenses — correctness, does-it-reproduce, security-relevance — and, where you can, run this pass on a **different model** than the one that built the floor, so it does not agree with itself.
+
+**Return a finding per row**: `confirmed` (the code applies the rule), `cited-not-applied` (the row claims applied but the code does not carry the rule), or `uncertain` (needs a human look). Deduplicate overlapping findings; group them by severity.
+
+**Hand the findings to the operator.** They are input to the operator's gate decision, not a gate of their own. A `cited-not-applied` finding is a prompt to fix the code (or downgrade the row to `deviated`/`n/a`) and re-run `check --strict` — never a silent override of the deterministic gate.
+
+## Definition of Done
+
+- Every `applied` row reviewed, with a confirmed / cited-not-applied / uncertain finding.
+- Findings handed to the operator; no exit code produced, no gate blocked.
+- Any `cited-not-applied` finding routed back to the code and re-checked deterministically.
+
+## Anti-patterns
+
+- Treating a clean `verify` pass as "the gate passed" — it is advisory; the deterministic `check --strict` is the gate.
+- Wiring `verify` into CI as a blocking step, or into an exit code — it never blocks.
+- Running `verify` **instead of** `check --strict` — it sits above the deterministic gate, it does not replace it.
+- Running it on the same model that wrote the code and trusting the agreement — use a different lens, ideally a different model.