runward 0.6.0

package/dist/lib/mission.js

@@ -0,0 +1,96 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { TEMPLATES } from "./paths.js";
+export const PHASES = [
+    {
+        id: "frame", label: "1 · Frame",
+        artifacts: [
+            { label: "Framing note", relPath: "framing.md", templateKey: "framing.md" },
+            { label: "Steering contract", relPath: "mission-contract.md", templateKey: "mission-contract.md" },
+        ],
+    },
+    {
+        id: "architect", label: "2 · Architect",
+        artifacts: [
+            { label: "Architecture note", relPath: "architecture.md", templateKey: "architecture.md" },
+            { label: "Decision matrix", relPath: "decision-matrix.md", templateKey: "decision-matrix.md" },
+            { label: "Decision journal (≥1 ADR)", relPath: "adr" },
+            { label: "Port contracts (≥1 filled)", relPath: "contracts" },
+        ],
+    },
+    {
+        id: "floor", label: "3 · Floor",
+        artifacts: [{ label: "Floor note (measured proof)", relPath: "floor.md", templateKey: "floor.md" }],
+    },
+    {
+        id: "govern", label: "5 · Govern (day zero)",
+        artifacts: [
+            { label: "Threat model", relPath: "governance/threat-model.md", templateKey: "threat-model.md" },
+            { label: "Evaluation rubric", relPath: "governance/evaluation-rubric.md", templateKey: "evaluation-rubric.md" },
+            { label: "Observability schema", relPath: "governance/observability-schema.md", templateKey: "observability-schema.md" },
+        ],
+    },
+    {
+        id: "handover", label: "6 · Hand over",
+        artifacts: [{ label: "Recovery runbook", relPath: "runbook.md", templateKey: "runbook.md" }],
+    },
+];
+export function findMissionRoot(cwd) {
+    let dir = cwd;
+    for (let i = 0; i < 12; i++) {
+        // A mission root contains runward/ with at least the framing note —
+        // a directory merely named "runward" (e.g. this repository) does not count.
+        if (existsSync(join(dir, "runward", "framing.md")))
+            return dir;
+        const parent = join(dir, "..");
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+// A placeholder is bracketed prose with whitespace ([the real process as observed…]),
+// 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;
+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"));
+        return adrs.length > 0 ? "filled" : "untouched";
+    }
+    // Special case: contracts directory — filled as soon as one .md is not the raw port-contract template.
+    if (a.relPath === "contracts") {
+        const template = readFileSync(join(TEMPLATES, "mission", "port-contract.md"), "utf8").trim();
+        const contracts = readdirSync(path).filter((f) => f.endsWith(".md"));
+        if (contracts.length === 0)
+            return "untouched";
+        const hasFilled = contracts.some((f) => readFileSync(join(path, f), "utf8").trim() !== template);
+        return hasFilled ? "filled" : "untouched";
+    }
+    const content = readFileSync(path, "utf8");
+    if (a.templateKey) {
+        const template = readFileSync(join(TEMPLATES, "mission", a.templateKey), "utf8");
+        if (content.trim() === template.trim())
+            return "untouched";
+    }
+    const placeholders = (content.match(PLACEHOLDER) || []).length;
+    if (placeholders >= 3)
+        return "in-progress";
+    return "filled";
+}
+export function analyze(missionDir) {
+    const phases = PHASES.map((spec) => {
+        const artifacts = spec.artifacts.map((artifact) => ({ artifact, state: artifactState(missionDir, artifact) }));
+        return { spec, artifacts, complete: artifacts.every((a) => a.state === "filled") };
+    });
+    const adrDir = join(missionDir, "adr");
+    const adrCount = existsSync(adrDir)
+        ? readdirSync(adrDir).filter((f) => /^ADR-\d+/.test(f) && !f.includes("0000")).length
+        : 0;
+    const firstIncomplete = phases.find((p) => !p.complete);
+    return { phases, adrCount, currentPhase: firstIncomplete ? firstIncomplete.spec.label : "all gates passed" };
+}

package/dist/lib/paths.js

@@ -0,0 +1,28 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const HERE = dirname(fileURLToPath(import.meta.url));
+/** Package root (works from dist/lib/ at runtime). */
+export const PKG_ROOT = join(HERE, "..", "..");
+export const TEMPLATES = join(PKG_ROOT, "templates");
+export const VERSION = JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf8")).version;
+/** Mission layout: template file -> destination inside runward/ */
+export const MISSION_LAYOUT = {
+    "framing.md": "framing.md",
+    "architecture.md": "architecture.md",
+    "decision-matrix.md": "decision-matrix.md",
+    "mission-contract.md": "mission-contract.md",
+    "reference-stack.md": "reference-stack.md",
+    "shared-bricks.md": "shared-bricks.md",
+    "floor.md": "floor.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",
+    "observability-schema.md": "governance/observability-schema.md",
+    "port-contract.md": "contracts/port-contract.md",
+    "runbook.md": "runbook.md",
+};
+export const WORKFLOWS = [
+    "method", "frame", "architect", "floor", "iterate",
+    "govern", "handover", "brownfield", "review", "decision-loop",
+];

package/dist/lib/styles.js

@@ -0,0 +1,60 @@
+import chalk from "chalk";
+// Respect the NO_COLOR standard (https://no-color.org/)
+if (process.env.NO_COLOR)
+    chalk.level = 0;
+// Runward palette — electric indigo, tuned for dark terminals.
+export const colors = {
+    primary: "#7B74FF", // electric indigo, readable on dark bg
+    primaryLight: "#A8A3FF", // highlights, current step
+    primaryDark: "#5B54F0", // borders, secondary accents
+    secondary: "#B0B8C4",
+    gray: "#8B95A5",
+    darkGray: "#5A6577",
+};
+export const c = {
+    primary: chalk.hex(colors.primary),
+    primaryLight: chalk.hex(colors.primaryLight),
+    primaryDark: chalk.hex(colors.primaryDark),
+    secondary: chalk.hex(colors.secondary),
+    gray: chalk.hex(colors.gray),
+    darkGray: chalk.hex(colors.darkGray),
+    bold: chalk.bold,
+    dim: chalk.dim,
+    white: chalk.white,
+    primaryBold: chalk.hex(colors.primary).bold,
+    success: chalk.green,
+    error: chalk.red,
+    warning: chalk.yellow,
+    info: chalk.cyan,
+    muted: chalk.hex(colors.gray),
+};
+export const status = {
+    success: (msg) => c.success("✓ ") + c.white(msg),
+    error: (msg) => c.error("✗ ") + c.white(msg),
+    warning: (msg) => c.warning("! ") + c.white(msg),
+    info: (msg) => c.info("• ") + c.white(msg),
+    skip: (msg) => c.darkGray("○ ") + c.gray(msg),
+};
+export function createHeader(title, subtitle) {
+    const width = Math.min(process.stdout.columns || 80, 72);
+    const inner = width - 4;
+    const pad = (s) => s + " ".repeat(Math.max(0, inner - stripAnsi(s).length));
+    const lines = [
+        c.primaryDark("┌" + "─".repeat(width - 2) + "┐"),
+        c.primaryDark("│ ") + pad(c.primaryBold(title)) + c.primaryDark(" │"),
+    ];
+    if (subtitle)
+        lines.push(c.primaryDark("│ ") + pad(c.gray(subtitle)) + c.primaryDark(" │"));
+    lines.push(c.primaryDark("└" + "─".repeat(width - 2) + "┘"));
+    return "\n" + lines.join("\n") + "\n";
+}
+export function section(title) {
+    return "\n" + c.primaryBold(title) + "\n" + c.darkGray("─".repeat(Math.min(title.length + 8, 60)));
+}
+export function isNonInteractive() {
+    return process.env.RUNWARD_YES === "1" || !process.stdout.isTTY;
+}
+function stripAnsi(s) {
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/\[[0-9;]*m/g, "");
+}

package/dist/lib/tools.js

@@ -0,0 +1,59 @@
+import { join } from "node:path";
+import { WORKFLOWS } from "./paths.js";
+const pointer = (wf) => [
+    "---",
+    `description: Runward — run the ${wf} workflow against the current mission state`,
+    "---",
+    "",
+    `Read \`runward/workflows/${wf}.md\` and execute it against the current mission state in \`runward/\`.`,
+    "Respect the charter in `AGENTS.md`. Do not mark the phase done unless its Definition of Done is demonstrably met.",
+    "",
+].join("\n");
+const rulesBody = [
+    "This project follows the Runward method (after the spec: ship and run).",
+    "The agent charter is `AGENTS.md` — its boundaries are non-negotiable.",
+    "The method lives in `runward/workflows/` (start with `method.md`); the mission state lives in `runward/`.",
+    "Every structural decision goes through `runward/workflows/decision-loop.md` and is locked as an ADR in `runward/adr/`,",
+    "with a dated re-evaluation trigger. Complexity is added only on an objective trigger — no trigger, no change.",
+    "",
+].join("\n");
+export const TOOL_PROFILES = [
+    {
+        id: "claude",
+        label: "Claude Code (.claude/commands/rw-*)",
+        files: (root) => WORKFLOWS.map((wf) => ({ path: join(root, ".claude", "commands", `rw-${wf}.md`), content: pointer(wf) })),
+    },
+    {
+        id: "cursor",
+        label: "Cursor (.cursor/rules/runward.mdc)",
+        files: (root) => [{
+                path: join(root, ".cursor", "rules", "runward.mdc"),
+                content: ["---", "description: Runward delivery method", "alwaysApply: true", "---", "", rulesBody].join("\n"),
+            }],
+    },
+    {
+        id: "copilot",
+        label: "GitHub Copilot (.github/copilot-instructions.md)",
+        files: (root) => [{
+                path: join(root, ".github", "copilot-instructions.md"),
+                content: "# Runward\n\n" + rulesBody,
+            }],
+    },
+    {
+        id: "gemini",
+        label: "Gemini CLI (GEMINI.md)",
+        files: (root) => [{
+                path: join(root, "GEMINI.md"),
+                content: "# Runward\n\n" + rulesBody,
+            }],
+    },
+    {
+        id: "windsurf",
+        label: "Windsurf (.windsurf/rules/runward.md)",
+        files: (root) => [{
+                path: join(root, ".windsurf", "rules", "runward.md"),
+                content: "# Runward\n\n" + rulesBody,
+            }],
+    },
+];
+export const TOOL_IDS = TOOL_PROFILES.map((t) => t.id);

package/dist/lib/write.js

@@ -0,0 +1,30 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, relative } from "node:path";
+import { c } from "./styles.js";
+export function makeWriter(opts) {
+    const stats = { written: 0, skipped: 0 };
+    function write(path, content) {
+        const rel = relative(opts.root, path) || path;
+        if (existsSync(path) && !opts.force) {
+            stats.skipped++;
+            console.log(`  ${c.darkGray("skip ")} ${c.gray(rel)} ${c.darkGray("(exists — --force to overwrite)")}`);
+            return;
+        }
+        if (opts.dryRun) {
+            stats.written++;
+            console.log(`  ${c.info("would write")} ${rel}`);
+            return;
+        }
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, content);
+        stats.written++;
+        console.log(`  ${c.success("write")} ${c.white(rel)}`);
+    }
+    function copy(src, dest, transform) {
+        let content = readFileSync(src, "utf8");
+        if (transform)
+            content = transform(content);
+        write(dest, content);
+    }
+    return { write, copy, stats };
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "runward",
+  "version": "0.6.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",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/stranxik/runward.git" },
+  "homepage": "https://runward.dev",
+  "bugs": { "url": "https://github.com/stranxik/runward/issues" },
+  "type": "module",
+  "bin": { "runward": "dist/cli.js" },
+  "files": ["dist", "templates", "README.md", "NOTICE.md"],
+  "engines": { "node": ">=20" },
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node test/smoke.js",
+    "prepublishOnly": "npm run build && node test/smoke.js"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0",
+    "chalk": "^5.6.0",
+    "commander": "^14.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/node": "^22.0.0"
+  }
+}

package/templates/mission/adr/ADR-0000-template.md

@@ -0,0 +1,38 @@
+# ADR-[number]: [short decision title]
+
+> **Usage.** An ADR records one structuring decision at the moment it is taken, with its context and consequences, so a future reader understands why the system is what it is. Ground rules: every decision has a lean default and an explicit evolution trigger; no decision is irreversible, because all are taken behind a boundary. The **reevaluation trigger is mandatory and dated** — an ADR without a reopening signal hardens into dogma. One ADR per decision: short, dated, numbered. Never edit an accepted ADR; write a new one that supersedes it. Replace every `[placeholder]`; delete this notice on delivery.
+
+**Date**: [YYYY-MM-DD]
+**Status**: [proposed | accepted | superseded by ADR-[n] | deprecated]
+**Deciders**: [names or roles]
+**Method**: [e.g. decision-loop: reality-check, sourced state of the art, challenge, durable position]
+
+## Context
+
+[The force that demands a decision now. The problem as observed, not as imagined. The hard constraints in play (sovereignty, regulated sector, legacy integration, confidentiality, human approval). What makes this choice structuring rather than local. State at which boundary the decision is taken: domain port, adapter, process boundary, contract.]
+
+## Decision
+
+[What is decided, phrased as a default being applied. One sentence of commitment, then only the strictly necessary detail. If the decision follows a default from the decision matrix, name it and say why it applies here.]
+
+## Alternatives discarded
+
+- **[Alternative A]**: [why discarded — the technical reason, not the habit.]
+- **[Alternative B]**: [why discarded.]
+- **[Alternative C]**: [why discarded, or tempered rather than eliminated.]
+
+## Consequences
+
+- **Positive**: [what this decision enables or simplifies.]
+- **Negative, accepted**: [the cost taken on knowingly — e.g. the explicit translation of a legacy adapter, or eventual consistency when crossing a process boundary.]
+- **On other boundaries**: [impact on contracts, observability, security, evaluation.]
+
+## Reevaluation trigger (mandatory, dated)
+
+[The objective, observable signal that will command reopening this decision — a measurable condition, never an intuition. Examples: latency or throughput proven insufficient; move to multi-instance; a genuinely parallelizable subtask appears; a new compliance constraint; behavioral divergence measured beyond a threshold. Until this signal appears, apply the decision without reopening it.]
+
+**Trigger set on**: [YYYY-MM-DD] · **Watched via**: [metric, dashboard, or review cadence]
+
+## References
+
+- [Public source, related ADR, port or contract concerned.]

package/templates/mission/architecture.md

@@ -0,0 +1,60 @@
+# Architecture Note: [system name]
+
+> **Usage.** Produce this note at the end of the `architect` workflow. It states boundaries before technology: the ports, the integration protocol, the default topology with its triggers, and what deliberately stays open. Keep it to a few pages — it is a map, not a detailed design dossier. Every structuring decision referenced here must already be locked in an ADR; the note cites, it does not decide. Replace every `[placeholder]`; delete this notice on delivery.
+
+**Date**: [YYYY-MM-DD] · **Version**: [vX.Y] · **Framing note**: [link] · **ADR journal**: [link]
+
+## 1. Context
+
+[One paragraph: the problem and success criterion from framing, and the floor this architecture must carry. No restating of the full framing note — link it.]
+
+## 2. Boundaries
+
+[The two boundaries that make the stack secondary.]
+
+- **Domain ports.** [How the domain expresses its needs as contracts, and why the model port is a port like any other: the reasoning engine is bound by its contract, not its brand — a replaceable adapter behind a stable port.]
+- **Integration protocol.** [The standardized tool protocol through which out-of-process capabilities are exposed and consumed. A service is an adapter that moved into its own process; the domain does not change.]
+
+## 3. Ports
+
+[One line per port; the full contract of each lives in its own port-contract spec.]
+
+| Port | Direction | Intent | Contract version | Spec |
+|---|---|---|---|---|
+| [ModelPort] | [secondary] | [provide a model completion] | [v0.1] | [link] |
+| [PersistencePort] | [secondary] | [persist the interaction log] | [v0.1] | [link] |
+| [ActionPort] | [secondary] | [execute an action — approval required: yes/no] | [v0.1] | [link] |
+| [EntryPort] | [primary] | [receive work: interface / API / tool protocol] | [v0.1] | [link] |
+
+## 4. Default topology and triggers
+
+[The starting silhouette and the signal that would change each default. Defaults apply now; triggers are crossed only in `iterate`.]
+
+| Default | Rationale | Evolution trigger |
+|---|---|---|
+| Modular hexagonal monolith | [one deployable, pure domain plus adapters] | [load, isolation, release-cycle, or availability signal] |
+| Single orchestrator | [composes, carries no business logic] | [genuinely parallelizable subtasks] |
+| Tool registry + middleware chain | [single transversal surface, thin channel] | [—] |
+| One core language, thin model SDK | [no heavy chain framework] | [mature library or proven performance need → sidecar] |
+
+## 5. What stays open
+
+[Explicitly undecided: language(s), framework, model provider, hosting. Each is an adapter decision, taken later behind the contracts above, justified by a local technical reason.]
+
+## 6. Legacy integration (if any)
+
+[Where the anticorruption layer sits, which dialect it translates, and the named cost of that translation. The boundary is never free on legacy.]
+
+## 7. Target, named
+
+[The architecture this system tends toward, per the framing note — named for direction, not built.]
+
+## 8. Decisions
+
+[Pointers only. Every structuring choice is locked in an ADR before appearing here.]
+
+| Decision | ADR |
+|---|---|
+| [starting topology] | [ADR-0001] |
+| [core language] | [ADR-0002] |
+| [legacy integration strategy] | [ADR-0003] |

package/templates/mission/decision-matrix.md

@@ -0,0 +1,37 @@
+# Decision Matrix
+
+How to use this file: every structural decision below carries **one sober default and one explicit trigger**. You start on the default. You only move when the trigger fires — measured, observed, named. **No trigger, no change. Every switch is an ADR** (`runward/adr/`), with the evidence that fired the trigger and a date to re-evaluate. Fill the matrix during the Architect phase; reopen it at every Iterate gate.
+
+| Decision | Sober default | Switch when |
+|---|---|---|
+| Core language | One typed language for the whole core, chosen for team fluency and ecosystem depth | A capability genuinely requires another runtime, and the need is measured and isolated |
+| Specialized capability | Implement it in the core language | A mature library exists only in another ecosystem (OCR, NLP, scientific computing) — wrap it as a sidecar behind a contract |
+| Hot-path component | Same runtime as the rest of the core | Profiling shows this component dominates latency or cost, and a faster runtime demonstrably fixes it |
+| Service split | Modular monolith, single process, boundaries enforced by ports | A module needs its own scaling profile, release cycle, or failure isolation — observed, not predicted |
+| Legacy integration | A thin adapter wrapping direct calls to the legacy system | Legacy concepts start leaking into your domain — install a full anticorruption layer that translates and validates at the boundary |
+| Number of agents | One agent, one loop | The task decomposes into parallelizable subtasks of real complexity, or context isolation is required — several agents under a single orchestrator |
+| Model abstraction | Every model call goes through a single port, one default model | Measured cost or quality spread justifies tiered routing behind the same port; bypassing the port for a direct SDK call requires an ADR of its own |
+| State | Stateless reducer: state in, decision out, nothing hidden inside the process | Audit, replay, or debugging needs history — immutable journal of events plus derived views |
+| Crossing the process boundary | In-process function calls behind ports | A consumer moves to another process — promote the port contract to a versioned network API; nothing else changes |
+| Contract evolution | Versioned contracts, additive changes only, consumers read tolerantly (unknown fields ignored) | A breaking change is unavoidable — expand-then-contract: serve both shapes, migrate every consumer, then retire the old one |
+| Memory & forgetting | Score each memory for value and decay; invalidate rather than delete, so nothing silently disappears | Memory grows past useful recall — consolidate into summaries that keep pointers back to their sources |
+| Evaluation | Deterministic tests for deterministic code, plus a guarded continuous evaluation loop for model behavior | The loop is stable and trusted — allow bounded auto-tuning: parameters only, inside hard limits, owned by a human |
+| Budget & discovery (multi-agent) | One central counter caps total spend across all agents | Contention on the counter slows the fleet — hand out lease blocks of budget that agents consume locally and return, paired with shared capability sheets: block allocation plus a shared capability registry, both handed out the moment budget leaves the central process |
+| Model unavailable | Retry with backoff against the primary provider | The outage persists — fall back to a second provider behind the same port; the domain never notices the swap |
+| Model change | Current model pinned; no silent upgrades | A candidate beats the incumbent in shadow deployment on your own rubric — staged rollout with rollback ready |
+| Waiting on human approval | Suspend the run, persist its state, rehydrate when the decision lands — never hold a process open | Approvals become a chronic bottleneck — never start blocking; batch low-urgency requests into a queue and revisit the autonomy boundary instead |
+| Non-critical vs sensitive | Non-critical dependencies fail open: the feature degrades, the system continues | The action touches money, private data leaving the system, or anything irreversible — fail closed: no guard response, no action |
+| Delegation autonomy | Bounded autonomy: the agent acts within templates, budgets, and pre-approved action lists | Evidence of consistent reliability on a class of actions — widen the bounds for that class, one ADR at a time |
+| Untrusted input | Least privilege everywhere, human approval on consequential actions, and never all three of: private data, untrusted content, external egress (2-of-3 rule) | A workflow claims to need all three — re-architect to break the triad: isolate, sanitize, or gate the exfiltration channel |
+| Agent identity | Each agent runs as its own principal, with its own permissions and audit trail | The agent must act on behalf of a user — explicit, bounded, revocable delegation; never shared credentials |
+| Execution secrets | The agent holds only a proxy token; real keys are injected at the network boundary, outside the model's reach | A target system cannot sit behind the proxy — isolate that call in a dedicated adapter the agent cannot introspect |
+| Shared brick | Consumed through a port; discovered through an index — and the index stays an index, not a brain | A brick gains multiple consumers — version its contract and run it as a product, still behind the port |
+
+## Express decision tree
+
+Four questions, in order. If none fires, stay on the sober default.
+
+1. **Does the task need a specialized library from another ecosystem?** → Sidecar behind a contract.
+2. **Does a component have its own load profile, release cycle, or isolation requirement?** → Split that service.
+3. **Is the work parallelizable, with real complexity in each branch?** → Multiple agents under one orchestrator.
+4. **Does the load require more than one instance?** → Externalize state first, then replicate.

package/templates/mission/evaluation-rubric.md

@@ -0,0 +1,60 @@
+# Evaluation Rubric: [agent or capability under evaluation]
+
+> **Usage.** A deterministic system is tested; an agentic system is tested **and** evaluated. This rubric serves the evaluation half: measuring the quality of non-deterministic behavior where a test can no longer answer true or false. Scoring follows an explicit rubric; every scenario carries expected and forbidden terms, which makes **abstention** (refusing to invent) weigh as much as recall. Evaluation is not a final gate but a continuous loop, sampled off the hot path from the trace stream. Scoring is hybrid: deterministic wherever a guarantee exists, a judge model only for the irreducibly behavioral. Two mandatory guards: a **hold-out the optimizer never sees**, and an **anchored judge** (pinned version, or an anchor set replayed at every judge change) — without them the quality series silently becomes incomparable. Replace every `[placeholder]`; delete this notice on delivery.
+
+**Version**: [vX.Y] · **Anchored judge**: [pinned version or anchor set] · **Rerun triggers**: [any change touching memory, prompts, or routing]
+
+## 1. Capabilities evaluated
+
+[Select and adapt the relevant capabilities. For long-memory benches, the six core ones below.]
+
+| Capability | What it verifies |
+|---|---|
+| Direct recall | [retrieve a fact given many turns earlier] |
+| Multi-constraint recall | [combine several scattered pieces of information into one answer] |
+| Knowledge update | [return the most recent value after a correction] |
+| Temporal reasoning | [state what was true at a given date; distinguish when a fact was learned from when it was valid] |
+| Abstention | [refuse to invent when the information was never given] |
+| Long session | [remember across enough turns to trigger summarization] |
+
+## 2. Scoring scale
+
+[Explicit and reproducible.]
+
+| Answer quality | Score |
+|---|---|
+| Complete — restates all key elements | [max] |
+| Partial — misses one | [intermediate] |
+| Vague but not wrong | [half] |
+| Wrong, or hallucinated where abstention was required | [zero] |
+
+## 3. Scenarios
+
+[One block per scenario: the multi-turn conversation, the final question, and the expected / forbidden terms.]
+
+### Scenario [ID] — capability: [target capability]
+
+- **Multi-turn conversation**: [describe the turns in order.]
+- **Final question**: [the question asked at the end.]
+- **Expected terms**: [elements a good answer must contain.]
+- **Forbidden terms**: [elements whose presence signals hallucination or leakage. For an abstention scenario, the right answer is a motivated refusal; any invented fact is forbidden.]
+
+## 4. Hold-out (non-gameable)
+
+[The strong guard that stops self-tuning from drifting toward whatever flatters the judge.]
+
+- **Composition**: [a subset of scenarios with verifiable ground truth, invisible to the optimizer.]
+- **Use**: [replayed to trigger rollback if its score drops, independently of the training score.]
+- **Limit**: [for purely subjective behavior without ground truth, the safety net reverts to human sampling; the self-tuning envelope stays narrow.]
+
+## 5. Judge anchoring
+
+[The judge is itself a model, and it will be updated.]
+
+- **Anchoring method**: [pinned version, or an anchor set replayed at every judge change to recalibrate the measure.]
+- **Judge scope**: [only irreducibly behavioral quality. The hard floor — safety, security, authorization, audit — stays deterministic, never delegated to the judge.]
+- **Action boundary**: [the loop produces signals and recommendations; acting on them goes through bounded, audited, pre-approved tuning or human validation — never autonomous self-rewriting.]
+
+## References
+
+- [Observability schema (the trace stream feeding this loop), related evaluation runbook, ADRs.]

package/templates/mission/floor.md

@@ -0,0 +1,47 @@
+# Floor Note: [system name]
+
+> **Usage.** Produce this note at the end of the `floor` workflow, once the floor runs on real traffic. It records what was shipped, what was measured against the success criterion, the gaps, and the next tier. A floor is not delivered, it is proven — this note is the proof record. Replace every `[placeholder]`; delete this notice on delivery.
+
+**Date**: [YYYY-MM-DD] · **Version**: [vX.Y] · **Architecture note**: [link] · **Success criterion**: [restate it verbatim from the framing note]
+
+## 1. Scope shipped
+
+[Exactly what the floor contains — and confirmation that the six floor components are present.]
+
+| Component | Status | Notes |
+|---|---|---|
+| Entry point ([interface / API / tool protocol]) | [shipped] | [matched to actual use, not a demo] |
+| Single orchestrator | [shipped] | [composes only, no business logic] |
+| Model port (real adapter, provider-agnostic) | [shipped] | [active with a key, deterministic fallback without] |
+| Persistence (immutable interaction log) | [shipped] | [attached to entity: [entity]] |
+| Deterministic guardrails | [shipped] | [classification, validation, mutation access control] |
+| Baseline observability + cost ceiling | [shipped] | [request ID propagated; per-run ceiling: [value]] |
+
+## 2. Proof against the success criterion
+
+[The measurement, on real traffic or a representative sample — never on cases picked to impress.]
+
+- **Traffic used**: [source, volume, period, representativeness.]
+- **Measured result**: [the number or observable fact, against the criterion.]
+- **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.]
+
+## 3. Gaps and deviations
+
+[Anything shipped differently from the architecture note, and anything the measurement revealed. Deviations were agreed with the sponsor, never silent.]
+
+| Gap / deviation | Impact | Agreed with sponsor |
+|---|---|---|
+| [gap] | [impact] | [date / reference] |
+
+## 4. Deferrals confirmed
+
+[The floor's named deferrals, restated with their triggers — the watchlist for `iterate`.]
+
+| Deferred capability | Trigger being watched | Signal observed so far |
+|---|---|---|
+| [long-term memory] | [measured cross-session need] | [none / early signs] |
+
+## 5. Next tier
+
+[What the evidence recommends: which trigger is closest to firing, which evolution it would command, and what proof would gate it. Or: hold the floor as is.]

package/templates/mission/framing.md

@@ -0,0 +1,58 @@
+# Framing Note: [system or mission name]
+
+> **Usage.** Produce this note at the end of the `frame` workflow, before any code. One page is enough. It records the problem, the observable success criterion, the floor/target split with named deferrals, and the hard constraints. It closes with the Definition of Ready check for the engagement. Replace every `[placeholder]`; delete this notice on delivery.
+
+**Date**: [YYYY-MM-DD] · **Sponsor**: [name or role] · **Entry mode**: [greenfield | brownfield M1–M4] · **Stopping tier**: [framing | floor | full chain]
+
+## 1. Problem
+
+[The real process as observed, not as idealized. Where the friction, manual rework, and waiting actually are. Who lives with it, how often.]
+
+## 2. Value
+
+[Where value is created if this works: time saved, errors avoided, quality raised, new service. Who benefits and at what frequency.]
+
+## 3. Observable success criterion
+
+[The measurable fact, observable on real traffic, that will say "it works". Not an impression. This criterion is what the floor will be proven against — without it, no gate can be crossed.]
+
+## 4. Floor
+
+[The smallest system that proves value on real traffic. Typically: one orchestrator, a model port, persistence, a few deterministic guardrails, baseline observability. List exactly what is in.]
+
+## 5. Target (named, not built)
+
+[The full architecture this system heads toward: elaborate memory, multi-agent, externalized state, distribution, continuous evaluation — whichever apply. Named to give direction only.]
+
+## 6. Named deferrals
+
+[Everything excluded from the floor, each with the objective trigger that will reactivate it.]
+
+| Deferred capability | Lean default in place | Trigger to revisit |
+|---|---|---|
+| [e.g. long-term memory] | [explicit per-turn context] | [measured need for cross-session continuity] |
+| [e.g. multi-agent] | [single orchestrator] | [genuinely parallelizable subtasks] |
+| [e.g. externalized state] | [in-memory, single instance] | [replication or shared state needed] |
+
+## 7. Hard constraints
+
+[Sovereignty, regulated sector, legacy integration, confidentiality, mandatory human approval on specific actions. These bound the solution space.]
+
+## 8. Presumed boundaries
+
+[The domain ports and integration protocol foreseen at this stage. Language and topology explicitly left open — they are adapter decisions for the `architect` phase.]
+
+## 9. Definition of Ready check
+
+[For each condition: met, or named as a risk owned by the sponsor. A missing condition does not block the start; it becomes the first object of discovery.]
+
+| Condition | Status | If missing: named risk |
+|---|---|---|
+| Real problem, identified sponsor | [met / risk] | [—] |
+| Observable success criterion | [met / risk] | [—] |
+| Floor-first principle accepted | [met / risk] | [—] |
+| Access to the real process and people | [met / risk] | [—] |
+| Usable data or a path to it | [met / risk] | [—] |
+| Access to technical infrastructure | [met / risk] | [—] |
+| Hard constraints known | [met / risk] | [—] |
+| Human available to decide and approve | [met / risk] | [—] |