runward 0.9.1 → 0.10.0

package/README.md

@@ -4,7 +4,9 @@
 
 [![npm](https://img.shields.io/npm/v/runward?style=for-the-badge&color=0a0a0a&label=npm)](https://www.npmjs.com/package/runward) [![License: MIT](https://img.shields.io/badge/License-MIT-0a0a0a?style=for-the-badge)](LICENSE) [![Doctrine: CC BY-ND 4.0](https://img.shields.io/badge/Doctrine-CC%20BY--ND%204.0-C9A45C?style=for-the-badge)](https://github.com/stranxik/designing-and-running-agentic-systems) [![Support via Ko-fi](https://img.shields.io/badge/%E2%98%95%20Support%20via%20Ko--fi-orange?style=for-the-badge)](https://ko-fi.com/stranxik)
 
-**From business need to a system that holds in production.**
+**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.*
 
 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.
 
@@ -56,9 +58,11 @@ New here? Follow [your first mission in 15 minutes](docs/first-mission.md).
 |---|---|
 | `runward init` | Scaffold the mission structure (wizard: entry mode, stopping tier, tool profiles) |
 | `runward check` | **Gate audit**: which deliverable, expected at which phase, is missing, started, or filled — exit code 1 on gaps |
+| `runward check --strict` | **Conformance gate**: verifies each phase's rule-conformance manifest — every CRITICAL/HIGH craft rule mapped to the phase is accounted for (applied with a `file:line`/test, deviated with an ADR, or reasoned `n/a`). **Deterministic and zero-LLM**: it proves a decision was traced, never the code's quality, and cannot be jailbroken by injection — rerun it and get the same verdict |
 | `runward status` | Mission snapshot: current gate, decision journal (ADRs), workflows |
 | `runward doctor` | Environment and installation checks |
 | `runward update` | Refresh `runward/workflows/` from the package — mission state never touched, local edits preserved unless `--force` |
+| `runward characterize` | **Read-only inventory** of an existing codebase (brownfield / retro-documentation) → `runward/characterization.md`: dependencies and lockfiles, entrypoints, CI, tests, git-log shape. Deterministic and zero-LLM; it parses artifacts at rest and never runs, builds, or writes to your code. Facts, not decisions — reconstructing the *why* stays yours |
 
 Global flags: `--yes`, `--dry-run`, `--verbose`, `--no-color`. Exit codes: 0 success, 1 gaps/warnings, 2 missing prerequisite.
 
@@ -107,6 +111,9 @@ Phase 5 is transverse: it starts at day zero, not after the incident.
 
 ## What makes it different
 
+- **The gate you own — deterministic and zero-LLM.** `runward check --strict` is a non-probabilistic, operator-owned exit-code gate: it cannot be jailbroken by injection (no model in the gate path) and reruns byte-for-byte. Every competitor gates on LLM generation plus human prose review; this one does not depend on an LLM to pass.
+- **Audit-ready evidence, not compliance theatre.** Craft rules carry an OWASP ASI (Top 10 for Agentic Applications) mapping — a universal, region-agnostic security posture — so the conformance manifest reads as supporting evidence. Security-only by default; it maps to your regime when you need one — ISO/IEC 42001 (global), NIST AI RMF (US), or the EU AI Act art. 13 technical file (EU) — see [`docs/compliance/`](docs/compliance/). An input to that work — never a conformity assessment, never a claim to certify.
+- **Never a runtime.** Runward writes nothing into `.git/`, installs nothing, and runs nothing of yours — it frames, gates and hands off. Your runtime and model are swappable adapters behind a port; the thing you depend on is never Runward.
 - **Floor, not MVP deck.** The floor is the smallest *running* system that proves value on real traffic. A presentation is not a floor.
 - **Evolution on evidence.** Multi-agent, long-term memory, microservices, a bigger model: each has a sober default and an explicit trigger. No trigger, no complexity. Every switch is an ADR.
 - **Security by architecture, not detection.** Prompt injection is constrained structurally (lethal trifecta, 2-of-3 rule), not filtered heuristically.

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
  * Runward CLI — after the spec: ship and run.
- * Commands: init (wizard), check (gate audit), status, doctor, update.
+ * Commands: init (wizard), check (gate audit), status, doctor, update, characterize.
  */
 import { Command } from "commander";
 import { VERSION } from "./lib/paths.js";
@@ -11,6 +11,7 @@ import { checkCommand } from "./commands/check.js";
 import { statusCommand } from "./commands/status.js";
 import { doctorCommand } from "./commands/doctor.js";
 import { updateCommand } from "./commands/update.js";
+import { characterizeCommand } from "./commands/characterize.js";
 // Exit codes: 0 = success · 1 = gaps/warnings · 2 = missing prerequisite
 process.on("uncaughtException", (err) => {
     if (err.name === "ExitPromptError")
@@ -59,6 +60,7 @@ program
     .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)")
+    .option("--coverage", "advisory: report deliverable + decision-ratification coverage (does not gate)")
     .action(checkCommand);
 program
     .command("status")
@@ -75,4 +77,10 @@ program
     .option("-p, --path <path>", "project directory")
     .option("--force", "overwrite locally modified workflows")
     .action(updateCommand);
+program
+    .command("characterize")
+    .description("read-only inventory of an existing codebase → runward/characterization.md (brownfield/retro-doc)")
+    .option("-p, --path <path>", "project directory (default: .)")
+    .option("--mine", "also propose candidate retroactive ADRs as DRAFT hypotheses (deterministic git archaeology, no model call)")
+    .action(characterizeCommand);
 program.parseAsync();

package/dist/commands/characterize.js

@@ -0,0 +1,63 @@
+import { existsSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { buildInventory, renderCharacterization, mineDrafts, renderDraft } from "../lib/characterize.js";
+import { makeWriter } from "../lib/write.js";
+import { c, createHeader, isNonInteractive, section, status } from "../lib/styles.js";
+import { VERSION } from "../lib/paths.js";
+/**
+ * Characterize an existing codebase (ADR-0014) — read-only, deterministic, zero-LLM.
+ * Emits runward/characterization.md: a factual inventory (dependencies, entrypoints,
+ * CI, tests, git-log shape). It parses artifacts at rest; it never runs, builds,
+ * installs, or writes to the target — only into runward/. The output is facts, not
+ * decisions: reconstructing the *why* stays the operator's job (ADR-0013).
+ * Exit codes: 0 = inventory produced, 2 = no readable target directory.
+ */
+export async function characterizeCommand(opts) {
+    const root = resolve(process.cwd(), opts.path ?? ".");
+    if (!existsSync(root) || !statSync(root).isDirectory()) {
+        console.error(status.error(`No readable directory at ${root}.`));
+        process.exit(2);
+    }
+    console.log(createHeader(`Runward v${VERSION} — characterize`, root));
+    console.log(section("Reading (read-only)"));
+    const inv = buildInventory(root);
+    const dryRun = process.env.RUNWARD_DRY_RUN === "1";
+    const generatedAt = isNonInteractive() && process.env.RUNWARD_NOW ? process.env.RUNWARD_NOW : new Date().toISOString().slice(0, 10);
+    const md = renderCharacterization(inv, generatedAt);
+    // Generated artifact, not mission state: always refresh it (idempotent).
+    const w = makeWriter({ force: true, dryRun, root });
+    w.write(join(root, "runward", "characterization.md"), md);
+    // --mine: deterministic git archaeology → candidate DRAFT ADRs (no model call, ADR-0014).
+    // force:false — never clobber a DRAFT the operator has started editing.
+    if (opts.mine) {
+        console.log(section("Candidate ADR-mining (--mine)"));
+        const candidates = mineDrafts(root, inv);
+        if (candidates.length === 0) {
+            console.log("  " + status.skip("no candidate decision found in the evidence at rest."));
+        }
+        else {
+            const dw = makeWriter({ force: false, dryRun, root });
+            for (const cand of candidates)
+                dw.write(join(root, "runward", "adr", `DRAFT-${cand.slug}.md`), renderDraft(cand, generatedAt));
+            console.log("  " + status.info(`${candidates.length} candidate decision(s) proposed as DRAFT hypotheses — ratify or delete each (they are not decisions until you own them).`));
+        }
+    }
+    console.log(section("Inventory"));
+    console.log(`  ${c.primaryBold("Ecosystems")}   ${c.white(inv.ecosystems.map((e) => e.name.split(" ")[0]).join(", ") || "none")}`);
+    console.log(`  ${c.primaryBold("Entrypoints")}  ${c.white(String(inv.entrypoints.length))}`);
+    console.log(`  ${c.primaryBold("CI")}           ${c.white(String(inv.ci.length))}`);
+    console.log(`  ${c.primaryBold("Tests")}        ${c.white(String(inv.tests.files))} file(s)`);
+    console.log(`  ${c.primaryBold("Git")}          ${c.white(inv.git ? `${inv.git.commits} commit(s), ${inv.git.authors} author(s)` : "not a git repo")}`);
+    console.log(section("Next steps"));
+    console.log("  " + c.white("1.") + " Review " + c.primary("runward/characterization.md") + c.darkGray(" — facts (confidence: high), not decisions."));
+    if (opts.mine) {
+        console.log("  " + c.white("2.") + " Review the " + c.primary("runward/adr/DRAFT-*.md") + " candidates with your agent: for each, write the real");
+        console.log("     " + c.white("why") + " and a trigger, set " + c.white("Status: accepted") + " and rename to " + c.primary("ADR-NNNN-*.md") + c.darkGray(", or delete it."));
+    }
+    else {
+        console.log("  " + c.white("2.") + " Run the " + c.primary("brownfield") + " workflow with your agent: reconstruct the architecture note and");
+        console.log("     retroactive ADRs. Each is a " + c.warning("hypothesis") + " until you confirm its " + c.white("why") + " and set its trigger.");
+    }
+    console.log("  " + c.white("3.") + " Then " + c.primary("runward check --strict") + c.darkGray(" — the gate stays red until you ratify each reconstructed decision."));
+    console.log();
+}

package/dist/commands/check.js

@@ -1,6 +1,6 @@
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { analyze, findMissionRoot } from "../lib/mission.js";
-import { conformance, driftReport } from "../lib/conformance.js";
+import { conformance, driftReport, unratifiedAdrs, decisionCoverage } 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";
@@ -14,7 +14,7 @@ import { VERSION } from "../lib/paths.js";
  * Exit codes: 0 = current gate clean, 1 = gaps, 2 = no mission found.
  */
 export async function checkCommand(opts) {
-    const root = findMissionRoot(join(process.cwd(), opts.path ?? "."));
+    const root = findMissionRoot(resolve(process.cwd(), opts.path ?? "."));
     if (!root) {
         console.error(status.error("No runward/ mission found here or above. Run `runward init` first."));
         process.exit(2);
@@ -86,6 +86,30 @@ export async function checkCommand(opts) {
                 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."));
         }
+        const unratified = unratifiedAdrs(mission);
+        if (unratified.length > 0) {
+            console.log(section("Reconstruction lifecycle (--strict)"));
+            for (const u of unratified)
+                console.log(`  ${c.error("✗")} ${c.white(u.file)}${c.darkGray(" — " + u.reason)}`);
+            console.log("  " + c.darkGray("ratify each: write the real why + a re-evaluation trigger and set Status: accepted (rename DRAFT→ADR), or remove it. A hypothesis is not a decision."));
+            strictGaps += unratified.length;
+        }
+    }
+    if (opts.coverage) {
+        console.log(section("Documentation coverage (advisory)"));
+        let filled = 0, totalArt = 0;
+        for (const phase of report.phases)
+            for (const { state } of phase.artifacts) {
+                totalArt++;
+                if (state === "filled")
+                    filled++;
+            }
+        console.log(`  ${c.primaryBold("Deliverables")}  ${c.white(`${filled}/${totalArt} filled`)}`);
+        const dc = decisionCoverage(mission);
+        console.log(`  ${c.primaryBold("Decisions")}     ${c.white(`${dc.ratified}/${dc.total} ratified`)}${dc.unratified.length ? c.warning(`  (${dc.unratified.length} to ratify)`) : ""}`);
+        for (const u of dc.unratified)
+            console.log(`     ${c.warning("◑")} ${c.white(u.file)}${c.darkGray(" — " + u.reason)}`);
+        console.log("  " + c.darkGray("advisory — a ratio of what is documented and ratified, not a claim of completeness. Does not affect the verdict."));
     }
     if (opts.hooks) {
         const after = runHooks(mission, "after", root);

package/dist/commands/init.js

@@ -1,4 +1,4 @@
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { readdirSync } from "node:fs";
 import { checkbox, input, select } from "@inquirer/prompts";
 import { TEMPLATES, MISSION_LAYOUT, VERSION } from "../lib/paths.js";
@@ -44,7 +44,7 @@ export async function initCommand(opts) {
     for (const t of unknown)
         console.log(status.warning(`Unknown tool profile "${t}" — supported: ${TOOL_IDS.join(", ")}`));
     // ── Write ─────────────────────────────────────────────────────────
-    const root = join(process.cwd(), dir);
+    const root = resolve(process.cwd(), dir);
     const mission = join(root, "runward");
     const w = makeWriter({ force: opts.force ?? false, dryRun, root });
     console.log(section("Mission structure"));

package/dist/commands/status.js

@@ -1,11 +1,11 @@
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { analyze, findMissionRoot } from "../lib/mission.js";
 import { c, createHeader, section } from "../lib/styles.js";
 import { VERSION, WORKFLOWS } from "../lib/paths.js";
 /** Mission snapshot: phase, ADR journal, framing summary, workflow presence. */
 export async function statusCommand(opts) {
-    const root = findMissionRoot(join(process.cwd(), opts.path ?? "."));
+    const root = findMissionRoot(resolve(process.cwd(), opts.path ?? "."));
     if (!root) {
         console.error(c.error("✗ ") + "No runward/ mission found. Run `runward init` first.");
         process.exit(2);

package/dist/commands/update.js

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { TEMPLATES, VERSION } from "../lib/paths.js";
 import { findMissionRoot } from "../lib/mission.js";
 import { makeWriter } from "../lib/write.js";
@@ -10,7 +10,7 @@ import { c, createHeader, section, status } from "../lib/styles.js";
  * Local edits are preserved unless --force.
  */
 export async function updateCommand(opts) {
-    const root = findMissionRoot(join(process.cwd(), opts.path ?? "."));
+    const root = findMissionRoot(resolve(process.cwd(), opts.path ?? "."));
     if (!root) {
         console.error(status.error("No runward/ mission found. Run `runward init` first."));
         process.exit(2);

package/dist/lib/characterize.js

@@ -0,0 +1,337 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+const SKIP_DIRS = new Set([
+    ".git", "node_modules", "dist", "build", "out", "coverage", "vendor",
+    ".next", ".nuxt", ".venv", "venv", "__pycache__", "target", ".turbo", ".cache",
+]);
+/** Bounded recursive walk (skips heavy dirs, caps depth) — read-only. */
+function walk(dir, depth, onFile) {
+    if (depth < 0)
+        return;
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const name of entries) {
+        const p = join(dir, name);
+        let st;
+        try {
+            st = statSync(p);
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory()) {
+            if (SKIP_DIRS.has(name))
+                continue;
+            walk(p, depth - 1, onFile);
+        }
+        else {
+            onFile(p, name);
+        }
+    }
+}
+function firstExisting(root, names) {
+    for (const n of names)
+        if (existsSync(join(root, n)))
+            return n;
+    return null;
+}
+function detectEcosystems(root) {
+    const out = [];
+    // Node / TypeScript — parsed in full.
+    if (existsSync(join(root, "package.json"))) {
+        let runtime = 0, dev = 0, names = [];
+        try {
+            const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+            names = Object.keys(pkg.dependencies ?? {});
+            runtime = names.length;
+            dev = Object.keys(pkg.devDependencies ?? {}).length;
+        }
+        catch { /* malformed manifest: still recorded, deps unknown */ }
+        out.push({
+            name: "Node / JavaScript / TypeScript",
+            manifest: "package.json",
+            lockfile: firstExisting(root, ["package-lock.json", "yarn.lock", "pnpm-lock.yaml", "bun.lockb"]),
+            runtimeDeps: runtime, devDeps: dev, depNames: names,
+        });
+    }
+    // Python.
+    const pyManifest = firstExisting(root, ["pyproject.toml", "requirements.txt", "setup.py", "Pipfile"]);
+    if (pyManifest) {
+        let runtime = 0;
+        if (pyManifest === "requirements.txt") {
+            try {
+                runtime = readFileSync(join(root, "requirements.txt"), "utf8").split("\n").filter((l) => l.trim() && !l.trim().startsWith("#")).length;
+            }
+            catch { /* unreadable */ }
+        }
+        out.push({ name: "Python", manifest: pyManifest, lockfile: firstExisting(root, ["poetry.lock", "Pipfile.lock", "uv.lock"]), runtimeDeps: runtime, devDeps: 0, depNames: [] });
+    }
+    // Go.
+    if (existsSync(join(root, "go.mod"))) {
+        let runtime = 0;
+        try {
+            runtime = readFileSync(join(root, "go.mod"), "utf8").split("\n").filter((l) => /^\s+[\w.\/-]+\s+v\d/.test(l)).length;
+        }
+        catch { /* unreadable */ }
+        out.push({ name: "Go", manifest: "go.mod", lockfile: firstExisting(root, ["go.sum"]), runtimeDeps: runtime, devDeps: 0, depNames: [] });
+    }
+    // Rust, Java, Ruby, PHP — presence + lockfile (rough).
+    const simple = [
+        ["Rust", "Cargo.toml", ["Cargo.lock"]],
+        ["Java (Maven)", "pom.xml", []],
+        ["Java (Gradle)", "build.gradle", ["gradle.lockfile"]],
+        ["Ruby", "Gemfile", ["Gemfile.lock"]],
+        ["PHP", "composer.json", ["composer.lock"]],
+    ];
+    for (const [name, manifest, locks] of simple) {
+        if (existsSync(join(root, manifest))) {
+            out.push({ name, manifest, lockfile: firstExisting(root, locks), runtimeDeps: 0, devDeps: 0, depNames: [] });
+        }
+    }
+    return out;
+}
+function detectEntrypoints(root) {
+    const found = new Set();
+    // Declared entrypoints in package.json.
+    try {
+        const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+        if (typeof pkg.main === "string")
+            found.add(pkg.main);
+        if (typeof pkg.bin === "string")
+            found.add(pkg.bin);
+        else if (pkg.bin && typeof pkg.bin === "object")
+            for (const v of Object.values(pkg.bin))
+                if (typeof v === "string")
+                    found.add(v);
+    }
+    catch { /* no/invalid package.json */ }
+    // Common convention files.
+    for (const f of ["index.ts", "index.js", "src/index.ts", "src/index.js", "src/main.ts", "main.py", "app.py", "src/main.rs", "cmd", "main.go"]) {
+        if (existsSync(join(root, f)))
+            found.add(f);
+    }
+    return [...found];
+}
+function detectCI(root) {
+    const out = [];
+    const wf = join(root, ".github", "workflows");
+    if (existsSync(wf)) {
+        try {
+            for (const f of readdirSync(wf))
+                if (/\.ya?ml$/.test(f))
+                    out.push(`.github/workflows/${f}`);
+        }
+        catch { /* unreadable */ }
+    }
+    for (const f of [".gitlab-ci.yml", "azure-pipelines.yml", ".circleci/config.yml", "Jenkinsfile", ".drone.yml"]) {
+        if (existsSync(join(root, f)))
+            out.push(f);
+    }
+    return out;
+}
+function detectContainers(root) {
+    const out = [];
+    for (const f of ["Dockerfile", "docker-compose.yml", "docker-compose.yaml", "compose.yaml", "vercel.json", "netlify.toml", "fly.toml", "Procfile", "Chart.yaml"]) {
+        if (existsSync(join(root, f)))
+            out.push(f);
+    }
+    return out;
+}
+function detectTests(root) {
+    const dirs = new Set();
+    let files = 0;
+    for (const d of ["test", "tests", "__tests__", "spec"])
+        if (existsSync(join(root, d)))
+            dirs.add(d);
+    walk(root, 5, (_p, name) => {
+        if (/\.(test|spec)\.[jt]sx?$/.test(name) || /_test\.go$/.test(name) || /^test_.*\.py$/.test(name) || /Test\.java$/.test(name))
+            files++;
+    });
+    return { dirs: [...dirs], files };
+}
+function gitShape(root) {
+    const git = (args) => execFileSync("git", ["-C", root, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    try {
+        git(["rev-parse", "--is-inside-work-tree"]); // throws if not a repo / git absent
+        const commits = parseInt(git(["rev-list", "--count", "HEAD"]), 10) || 0;
+        const last = git(["log", "-1", "--format=%as"]);
+        const first = git(["log", "--max-parents=0", "-1", "--format=%as"]);
+        const authors = git(["shortlog", "-sne", "HEAD"]).split("\n").filter((l) => l.trim()).length;
+        return { commits, first, last, authors };
+    }
+    catch {
+        return null;
+    }
+}
+/** Build the read-only inventory of an existing codebase. */
+export function buildInventory(root) {
+    let fileCount = 0;
+    walk(root, 6, () => { fileCount++; });
+    return {
+        root,
+        ecosystems: detectEcosystems(root),
+        entrypoints: detectEntrypoints(root),
+        ci: detectCI(root),
+        containers: detectContainers(root),
+        tests: detectTests(root),
+        git: gitShape(root),
+        fileCount,
+    };
+}
+/** Render the inventory as `characterization.md` — facts only, never decisions. */
+export function renderCharacterization(inv, generatedAt) {
+    const L = [];
+    L.push(`# Characterization — ${basename(inv.root) || "system"}`);
+    L.push("");
+    L.push(`> \`confidence: high\` · generated by \`runward characterize\` on ${generatedAt} · **read-only, deterministic (no LLM).**`);
+    L.push("> This is a factual inventory of an existing system, not a set of decisions. Nothing here explains *why* the");
+    L.push("> system is the way it is — reconstructing that is the operator's job (see next steps). Re-run to refresh.");
+    L.push("");
+    L.push("## Languages & build");
+    L.push("");
+    if (inv.ecosystems.length === 0)
+        L.push("_No dependency manifest found at the root._");
+    else {
+        L.push("| Ecosystem | Manifest | Lockfile | Runtime deps | Dev deps |");
+        L.push("|---|---|---|---|---|");
+        for (const e of inv.ecosystems) {
+            L.push(`| ${e.name} | \`${e.manifest}\` | ${e.lockfile ? `\`${e.lockfile}\`` : "**none** (unpinned)"} | ${e.runtimeDeps || "—"} | ${e.devDeps || "—"} |`);
+        }
+    }
+    L.push("");
+    const withNames = inv.ecosystems.find((e) => e.depNames.length);
+    if (withNames) {
+        L.push(`## Runtime dependencies (${withNames.manifest})`);
+        L.push("");
+        L.push(withNames.depNames.map((n) => `\`${n}\``).join(" · "));
+        L.push("");
+    }
+    L.push("## Entrypoints");
+    L.push("");
+    L.push(inv.entrypoints.length ? inv.entrypoints.map((e) => `- \`${e}\``).join("\n") : "_None detected by convention._");
+    L.push("");
+    L.push("## CI / pipelines");
+    L.push("");
+    L.push(inv.ci.length ? inv.ci.map((f) => `- \`${f}\``).join("\n") : "_No CI configuration detected._");
+    L.push("");
+    L.push("## Containers / deployment");
+    L.push("");
+    L.push(inv.containers.length ? inv.containers.map((f) => `- \`${f}\``).join("\n") : "_No container/deploy descriptor detected._");
+    L.push("");
+    L.push("## Tests");
+    L.push("");
+    L.push(`- Test directories: ${inv.tests.dirs.length ? inv.tests.dirs.map((d) => `\`${d}/\``).join(", ") : "_none_"}`);
+    L.push(`- Test files (by naming convention): **${inv.tests.files}**`);
+    L.push("");
+    L.push("## Git history (shape only)");
+    L.push("");
+    if (inv.git) {
+        L.push(`- Commits: **${inv.git.commits}** · Span: ${inv.git.first} → ${inv.git.last} · Distinct authors: **${inv.git.authors}**`);
+        L.push("- Counts only — the log tells you *what* changed and *when*, rarely *why*. The *why* is a decision to reconstruct, not a fact to read.");
+    }
+    else {
+        L.push("_Not a git repository, or git unavailable — history shape could not be read._");
+    }
+    L.push("");
+    L.push(`_Scanned ~${inv.fileCount} files (heavy directories skipped)._`);
+    L.push("");
+    L.push("## Next steps (operator)");
+    L.push("");
+    L.push("1. This inventory is **facts**, not decisions. Nothing here has been ratified.");
+    L.push("2. Run the **brownfield** workflow (`runward/workflows/brownfield.md`) with your agent: reconstruct the architecture note and the retroactive ADRs — each starts as a *hypothesis* until you confirm its *why* and set its re-evaluation trigger.");
+    L.push("3. Then `runward check` (and `--strict` once you have manifests) — the gate stays red until each reconstructed decision is ratified by you, not your agent.");
+    L.push("");
+    return L.join("\n") + "\n";
+}
+const slugify = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+const DEP_FAMILIES = [
+    { match: /^(express|fastify|koa|@nestjs\/core|next|nuxt|react|vue|svelte|@angular\/core|django|flask|fastapi|rails|sinatra|laravel|symfony|spring-boot)/i, family: "web framework / UI" },
+    { match: /^(pg|mysql2?|mongodb|mongoose|@prisma\/client|prisma|typeorm|sequelize|redis|ioredis|sqlalchemy|gorm|diesel)/i, family: "data store / ORM" },
+    { match: /^(bullmq|bull|amqplib|kafkajs|celery|sidekiq|nats)/i, family: "queue / messaging" },
+    { match: /^(openai|@anthropic-ai\/sdk|anthropic|langchain|@langchain\/|llamaindex|@ai-sdk\/|cohere-ai)/i, family: "AI / model provider" },
+    { match: /^(@aws-sdk\/|aws-sdk|@google-cloud\/|@azure\/|firebase|stripe)/i, family: "external service SDK" },
+];
+function firstSeen(root, file) {
+    try {
+        const out = execFileSync("git", ["-C", root, "log", "--diff-filter=A", "--reverse", "--format=%as", "--", file], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+        return out.split("\n")[0] || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Propose *candidate* structural decisions from evidence at rest — deterministic, no model call.
+ * Covers the stack/language choice, containerization, the CI pipeline, and notable dependency
+ * families. Each is a hypothesis with provenance; the *why* is left for the operator (ADR-0013).
+ */
+export function mineDrafts(root, inv) {
+    const out = [];
+    for (const eco of inv.ecosystems) {
+        const seen = firstSeen(root, eco.manifest);
+        out.push({
+            slug: `stack-${slugify(eco.name.split(/[ /]/)[0])}`,
+            title: `Adopt ${eco.name} as the core stack`,
+            evidence: [`\`${eco.manifest}\`${eco.lockfile ? ` + \`${eco.lockfile}\`` : " (no lockfile — unpinned)"}`, seen ? `first seen ${seen}` : "manifest at repo root"],
+        });
+    }
+    if (inv.containers.length) {
+        out.push({ slug: "deployment-target", title: `Deploy/package via ${inv.containers[0]}`, evidence: inv.containers.map((f) => `\`${f}\``) });
+    }
+    if (inv.ci.length) {
+        out.push({ slug: "ci-pipeline", title: "Gate delivery through a CI pipeline", evidence: inv.ci.map((f) => `\`${f}\``) });
+    }
+    let depCount = 0;
+    for (const eco of inv.ecosystems) {
+        for (const dep of eco.depNames) {
+            if (depCount >= 8)
+                break;
+            const fam = DEP_FAMILIES.find((f) => f.match.test(dep));
+            if (!fam)
+                continue;
+            depCount++;
+            out.push({ slug: `dep-${slugify(dep)}`, title: `Depend on ${dep} (${fam.family})`, evidence: [`\`${dep}\` in \`${eco.manifest}\``] });
+        }
+    }
+    return out;
+}
+/** Render one candidate as a DRAFT-*.md — a hypothesis with provenance, `why: UNKNOWN`, no verdict. */
+export function renderDraft(cand, generatedAt) {
+    const L = [];
+    L.push(`# DRAFT — ${cand.title}`);
+    L.push("");
+    L.push("**Status**: hypothesis");
+    L.push(`**Date**: ${generatedAt}`);
+    L.push("**Deciders**: (unratified — the operator must own this)");
+    L.push("");
+    L.push("> Reconstructed by `runward characterize --mine` from evidence at rest — a **candidate decision**,");
+    L.push("> not a fact. Ratify it: write the real *why* and the alternatives you rejected, set a re-evaluation");
+    L.push("> trigger, put your name in Deciders, set `Status: accepted`, and rename this file to");
+    L.push("> `ADR-NNNN-<slug>.md`. Or delete it if it was never a real decision. `runward check --strict` stays");
+    L.push("> red until you do.");
+    L.push("");
+    L.push("## Evidence");
+    L.push("");
+    for (const e of cand.evidence)
+        L.push(`- ${e}`);
+    L.push("");
+    L.push("## Decision (reconstructed — confirm or correct)");
+    L.push("");
+    L.push(`${cand.title}.`);
+    L.push("");
+    L.push("## Why");
+    L.push("");
+    L.push("why: UNKNOWN — the operator must supply the rationale; it is not recoverable from code or history.");
+    L.push("");
+    L.push("## Reevaluation trigger (mandatory)");
+    L.push("");
+    L.push("TODO — under what objective signal should this decision be reopened?");
+    L.push("");
+    return L.join("\n") + "\n";
+}

package/dist/lib/conformance.js

@@ -73,6 +73,53 @@ function adrExists(missionDir, evidence) {
     const dir = join(missionDir, "adr");
     return existsSync(dir) && readdirSync(dir).some((f) => f.toUpperCase().startsWith(id));
 }
+/**
+ * The reconstruction lifecycle (ADR-0013/0014). A retroactively reconstructed decision is a
+ * *hypothesis* until the operator ratifies it — writes the real *why*, sets a re-evaluation
+ * trigger, and marks it accepted. This returns the ADRs in runward/adr/ still unratified, by
+ * deterministic marker: a DRAFT- filename, a `Status: hypothesis`, or a `why: UNKNOWN` left in
+ * place. The gate fails while any remain — an agent's guess must not pass as a decision.
+ */
+export function unratifiedAdrs(missionDir) {
+    const dir = join(missionDir, "adr");
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const f of readdirSync(dir)) {
+        if (!f.endsWith(".md"))
+            continue;
+        if (/^DRAFT-/i.test(f)) {
+            out.push({ file: f, reason: "DRAFT — reconstructed decision not yet ratified" });
+            continue;
+        }
+        let body = "";
+        try {
+            body = readFileSync(join(dir, f), "utf8");
+        }
+        catch {
+            continue;
+        }
+        if (/^\s*(?:\*\*status\*\*|status)\s*:\s*hypothesis\b/im.test(body))
+            out.push({ file: f, reason: "Status: hypothesis" });
+        else if (/why\s*:\s*UNKNOWN\b/i.test(body))
+            out.push({ file: f, reason: "why: UNKNOWN — the operator must supply it" });
+    }
+    return out;
+}
+/**
+ * Decision-ratification coverage (ADR-0013): how many recorded decisions are ratified vs still
+ * hypotheses. Advisory — a deterministic ratio, never a claim of completeness. Excludes the
+ * scaffolded ADR-0000 template and any README.
+ */
+export function decisionCoverage(missionDir) {
+    const dir = join(missionDir, "adr");
+    const unratified = unratifiedAdrs(missionDir);
+    let total = 0;
+    if (existsSync(dir)) {
+        total = readdirSync(dir).filter((f) => f.endsWith(".md") && f !== "ADR-0000-template.md" && f.toUpperCase() !== "README.MD").length;
+    }
+    return { total, ratified: Math.max(0, total - unratified.length), unratified };
+}
 // 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. */

package/dist/lib/paths.js

@@ -15,6 +15,7 @@ export const MISSION_LAYOUT = {
     "reference-stack.md": "reference-stack.md",
     "shared-bricks.md": "shared-bricks.md",
     "floor.md": "floor.md",
+    "gap-analysis.md": "gap-analysis.md",
     "adr/ADR-0000-template.md": "adr/ADR-0000-template.md",
     "threat-model.md": "governance/threat-model.md",
     "evaluation-rubric.md": "governance/evaluation-rubric.md",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runward",
-  "version": "0.9.1",
+  "version": "0.10.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/gap-analysis.md

@@ -0,0 +1,44 @@
+# Gap analysis — [system or mission name]
+
+> Brownfield / retro-documentation artifact (workflow `brownfield.md`, mode M3). A **section-by-section
+> audit of an existing system**: what is there, what is missing, and — for each gap — the trigger that
+> forces closing it and the reconstructed decision that records the choice. Start it from the facts in
+> `characterization.md` (run `runward characterize`). Everything here is a **finding or a hypothesis**
+> until you, the operator, ratify it — never a claim that the system is safe or complete.
+
+## How to fill this
+
+For each dimension below: state what **exists** in the current system (fact, from characterization or
+observation), what is **missing or unknown** (the gap), the **trigger** under which the gap must be
+closed (a date, an audit, a next change), and the **ADR** that records the reconstructed decision (a
+`DRAFT-*` hypothesis until you ratify it — write the real *why* + a re-evaluation trigger and set
+`Status: accepted`). Leave `why: UNKNOWN` where you cannot yet source the rationale; `runward check
+--strict` will keep the gate red until it is filled.
+
+| Dimension | What exists (fact) | Gap / unknown | Trigger to close | Reconstructed ADR |
+|---|---|---|---|---|
+| **Boundaries & architecture** | | | | |
+| **Ports & contracts** | | | | |
+| **Model / non-determinism boundary** | | | | |
+| **State & memory** | | | | |
+| **Governance — threat model** | | | | |
+| **Governance — evaluation** | | | | |
+| **Observability & tracing** | | | | |
+| **Security — untrusted input / trifecta** | | | | |
+| **Resilience & cost controls** | | | | |
+| **Tests / characterization** | | | | |
+| **Handover / transmission** | | | | |
+
+## Findings summary
+
+- **Critical gaps** (block production / audit): …
+- **Deferred gaps** (named, each with a trigger): …
+- **Reconstructed decisions to ratify**: list the `DRAFT-*` ADRs still `Status: hypothesis` — the
+  operator owns each *why* and trigger before it counts (see the ratification loop). The reconstruction
+  is the cheap part; owning it is the deliverable.
+
+## Re-entry point
+
+After this audit, re-enter the six-phase chain at the right rung (`brownfield.md`): typically Architect
+(reconstruct boundaries and ports) then Govern (retrofit the threat model, evaluation, observability),
+proving each on real behavior before touching anything.