v0.2.0: runtime, CLI, BYOK adapters, phase-loop enforcement

OpenWar evolves from a system-prompt overlay into a runnable runtime.
The framework doc stays canonical; the runtime adds rails that make
the framework's rules enforceable instead of advisory.

Foundation:
- Zero runtime dependencies. devDeps: typescript, tsx, @types/node.
- Strict ESM/NodeNext TypeScript.
- node:test runner via tsx for the test suite.

Brief layer:
- Hand-rolled YAML subset parser (no js-yaml dep).
- parseBrief, validateBrief, renderBriefForAgent, generateBriefId.
- brief_id autogen as YYYY-MM-DD-<6-char-random> when missing.

Detector suite (regex/pattern only, no LLM judging):
- confirmation-summary: detects Phase 0 marker or section headings.
- blocker: explicit Phase 2 marker plus heuristic phrases.
- destructive: action-intent verbs with negation guard, cross-checks
  brief.authorized_costs for pre-approval.
- banned-phrases: voice-rule warnings (Certainly, leverage, etc.).
- phase-marker, completion.
- All detectors are code-fence aware so docs about the rules don't
  trip them.

Adapters (BYOK via env vars, streaming via native fetch + SSE):
- Anthropic, OpenAI, Gemini, Grok, OpenAI-compat (OpenRouter, Groq,
  Together, Ollama, vLLM, llama.cpp).
- MockAdapter for deterministic tests.

State:
- JSON session files plus append-only JSONL transcripts at
  ~/.openwar/sessions/.
- Atomic writes via tmp+rename.
- Schema-version gated.

Phase loop:
- intake -> execute -> {blocker / destructive / completion}.
- Destructive denial loop records denial as user msg and re-invokes
  execute.
- Auto-pilot and gated modes both wired.
- max_steps=30 failsafe.

CLI:
- run, resume, list, inspect [--transcript], validate, adapters,
  version, --help.
- Bin shim handles both compiled-dist and tsx-from-source paths.

Examples:
- creative-brief.md (gated, generation_credits authorized).
- engineering-brief.md (auto, scope-locked, filesystem_write
  authorized).
- examples/README.md explains how to run each.

Tests: 31 passing across brief, detectors, runner.

CI: GitHub Actions matrix (Ubuntu/macOS/Windows x Node 20/22)
running lint -> build -> test.

Bug caught during build: destructive detector matched negated intent
('I will not force-push'), creating an infinite Phase-3-denial loop.
Added a negation guard plus a regression test.

Author: PythonLuvr

.github/workflows/test.yml

@@ -0,0 +1,31 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        node-version: [20.x, 22.x]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - name: Install
+        run: npm install --no-audit --no-fund
+      - name: Lint (em dashes)
+        run: npm run lint:em-dashes
+      - name: Lint (sanity)
+        run: npm run lint:sanity
+      - name: Build
+        run: npm run build
+      - name: Test
+        run: npm test

.gitignore

@@ -4,3 +4,11 @@
 .idea/
 .vscode/
 node_modules/
+dist/
+*.log
+.env
+.env.local
+.openwar/
+coverage/
+*.tsbuildinfo
+DEFERRED.md

CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## 0.2.0
+
+Runtime release. The framework gets a real engine.
+
+### Added
+
+- Node / TypeScript package with a `openwar` CLI.
+- Brief parser and validator (markdown + frontmatter), with kebab-case project slugs, optional `brief_id` autogen, scope-lock and mode overrides, and an `authorized_costs` list that pre-approves categories of destructive actions.
+- Phase-aware runner enforcing Phase 0 (Confirmation Summary required), Phase 1 (gated or auto-pilot execution), Phase 2 (blocker halt + persist + resume), Phase 3 (destructive flag, explicit per-session approval), and Phase 4 (canonical completion report).
+- Deterministic detectors for confirmation, blocker, destructive intent, banned phrases, phase markers, and completion. Regex / pattern based; no second LLM.
+- BYOK adapters: Anthropic Claude, OpenAI, Google Gemini, xAI Grok, and an OpenAI-compatible adapter that handles OpenRouter / Groq / Together / Ollama / vLLM / llama.cpp.
+- MockAdapter for deterministic offline tests.
+- Session persistence at `~/.openwar/sessions/` (one JSON per session + JSONL append-only transcript). `openwar resume <brief_id>` reopens.
+- CLI commands: `run`, `resume`, `list`, `inspect`, `validate`, `adapters`, `version`.
+- Library surface: `run`, `parseBrief`, `validateBrief`, all adapters, all detectors, and state helpers exported from the package root so integrators (e.g. War Room) can embed the runtime.
+- Examples: a gated creative brief and an auto-pilot engineering brief.
+- Cross-platform CI (Ubuntu, macOS, Windows on Node 20 and 22) with em-dash and personal-data sanity lints in front of the build / test pipeline.
+
+### Changed
+
+- `openwar.md` clarified: OpenWar is now both a framework (the markdown doc) and a runtime (this package). The "not a runtime" sentence in v0.1 has been removed.
+
+### Notes for War Room integrators
+
+The library surface is stable for v0.2. Re-exporting from `openwar` (root) gives you everything War Room needs to swap its raw adapter path for the OpenWar phase loop in channels where the operator selects the framework.
+
+## 0.1.0
+
+Initial release. System-prompt-only framework. Single markdown file (`openwar.md`), reference brief template, MIT license.

README.md

@@ -4,80 +4,154 @@
 
 <h1 align="center">OpenWar</h1>
 
-<p align="center"><strong>The framework that ships in <a href="https://github.com/pythonluvr/war-room">War Room</a>. Use it anywhere.</strong></p>
+<p align="center"><strong>A framework and a runtime for agent behavior that doesn't go off the rails.</strong></p>
 
-OpenWar is a system prompt that turns any LLM-based agent (Claude, GPT, Gemini, others) into something that behaves like a senior peer instead of a customer service rep. It confirms briefs before acting, breaks work into phases, asks before doing anything destructive, and writes like an adult who's busy.
+OpenWar replaces eager-customer-service-rep defaults with the behavior of a senior peer. It confirms briefs before acting, breaks work into phases, asks before doing anything destructive, and writes like an adult who's busy.
 
-It's a single markdown file. Drop it into your agent's system prompt, Claude Code's `CLAUDE.md`, Cursor's settings, Hermes config, OpenClaw skills, anywhere, and your agent's behavior changes.
+You can use it two ways:
 
-## What's in it
+1. **As a runtime** (new in v0.2). Install the package, point it at a brief, watch the phase machine enforce the framework against any BYOK LLM. The runtime is opinionated: no flag to disable Phase 3, no way to skip the Confirmation Summary.
+2. **As a system prompt** (v0.1, still supported). Paste [`openwar.md`](./openwar.md) into Claude Code's CLAUDE.md, Cursor's rules, Hermes, OpenClaw, or anywhere else. The agent's behavior changes; nothing else does.
 
-- **Phase architecture**: every task moves through Brief Intake → Execution → (Blocker / Destructive Flag) → Completion. Operators can interrupt at any phase.
-- **Confirmation Summary**: agent never starts work without acknowledging what it heard.
-- **Per-step vs auto-pilot mode**: operators pick how much gating they want; agents respect it.
-- **Hard rules against** invented next steps, hallucinated capabilities, unauthorized actions, blind retries past blockers.
-- **Pre-mortem trigger** for strategic / problem-solving / creative / cost-spending work.
-- **Voice rules**: banned filler phrases ("Certainly", "Absolutely", "leverage"...), peer-level tone.
-- **"Best solution, not the fast one"**: agent leads with the gold-standard path by default, not stopgaps.
+The framework doc and the runtime are the same source of truth. The doc tells the model what to do. The runtime makes sure it actually does it.
 
-Read the full framework: [`openwar.md`](./openwar.md).
+## Quick start (runtime)
 
-## Install
-
-### Claude Code
+```bash
+npx pythonluvr/openwar run examples/creative-brief.md --adapter anthropic
+```
 
-Append OpenWar to your global CLAUDE.md so every Claude Code session loads it automatically:
+Or install:
 
 ```bash
-mkdir -p ~/.claude
-curl -fsSL https://raw.githubusercontent.com/pythonluvr/openwar/main/openwar.md >> ~/.claude/CLAUDE.md
+npm install -g pythonluvr/openwar
+export ANTHROPIC_API_KEY=...
+openwar run examples/engineering-brief.md
 ```
 
-Or for a single project:
+Provide an API key for whichever adapter you pick:
+
+| Adapter         | Env var                  | Default model         |
+|-----------------|--------------------------|-----------------------|
+| `anthropic`     | `ANTHROPIC_API_KEY`      | `claude-sonnet-4-6`   |
+| `openai`        | `OPENAI_API_KEY`         | `gpt-4o`              |
+| `gemini`        | `GEMINI_API_KEY`         | `gemini-2.0-flash`    |
+| `grok`          | `XAI_API_KEY`            | `grok-2-latest`       |
+| `openai-compat` | `OPENAI_COMPAT_API_KEY`  | (specify with `--base-url`) |
+
+`openai-compat` covers OpenRouter, Groq, Together, Ollama, vLLM, llama.cpp, and anything else speaking OpenAI's chat-completions protocol.
+
+## What the runtime enforces
+
+| Phase   | What happens                                                                                     | What blocks |
+|---------|--------------------------------------------------------------------------------------------------|-------------|
+| Phase 0 | Agent must produce a Confirmation Summary with Objective / Deliverables / Constraints / Tools / Unknowns. | No execution until the operator accepts. |
+| Phase 1 | Agent executes step by step. Gated mode pauses between steps; auto-pilot runs through clean ones. | Banned phrases warn. |
+| Phase 2 | If the agent declares it's blocked, the runtime halts the session and persists state. | Resume with `openwar resume <brief_id>`. |
+| Phase 3 | If the agent announces intent to do something destructive or out-of-directive, the runtime stops and asks for explicit yes. | Authorization can be pre-approved per category in the brief's `authorized_costs`. |
+| Phase 4 | Agent produces a concise completion report. | None. |
+
+The phase loop is enforced by deterministic pattern detectors. No second LLM, no judging. If the agent skips the Confirmation Summary, the runtime asks it to restate before letting execution start.
+
+## CLI
+
+```text
+openwar run <brief.md> [--adapter <id>] [--model <name>] [--mode gated|auto]
+                       [--resume] [--ephemeral]
+openwar resume <brief_id>
+openwar list
+openwar inspect <brief_id> [--transcript]
+openwar validate <brief.md>
+openwar adapters
+openwar version
+```
 
-```bash
-curl -fsSL https://raw.githubusercontent.com/pythonluvr/openwar/main/openwar.md >> ./CLAUDE.md
+Sessions persist to `~/.openwar/sessions/` as JSON + JSONL transcript. Resume with `openwar resume <brief_id>`. `--ephemeral` skips persistence (used by tests and integrators).
+
+## Use as a library
+
+```ts
+import { run, MockAdapter, AnthropicAdapter } from "openwar";
+
+const adapter = new AnthropicAdapter({ id: "anthropic", model: "claude-sonnet-4-6" });
+const result = await run({ briefPath: "./brief.md", adapter });
+
+if (!result.completed) {
+  console.error(`Halted at ${result.final_phase}: ${result.halt_reason}`);
+}
 ```
 
-### Cursor
+War Room and other integrators consume OpenWar this way; the runtime is the framework's enforcement surface.
 
-Cursor → Settings → Rules for AI → paste the contents of [`openwar.md`](./openwar.md).
+## Brief format
 
-### War Room
+Briefs are markdown with required frontmatter. A reference template ships at [`templates/brief.md`](./templates/brief.md).
 
-War Room ships OpenWar as the bundled default framework. Toggle in `Settings → Agent → Framework`. Nothing to install, it's already there.
+```yaml
+---
+project: <slug>                    # required, kebab-case
+brief_id: YYYY-MM-DD-NNN           # optional; auto-generated if absent
+deadline: YYYY-MM-DD               # optional
+scope_locked: true|false           # if true, refuse out-of-scope additions
+mode: gated|auto                   # optional override of per-step-vs-auto
+authorized_costs:                  # pre-approves these destructive categories
+  - filesystem_write
+  - generation_credits
+  - git_push
+---
+```
 
-### Anything else (Hermes, OpenClaw, custom)
+Recognized `authorized_costs` categories include `filesystem_delete`, `git_history_rewrite`, `git_push`, `deploy`, `external_message`, `paid_api`, `package_change`, `ci_modify`, `process_kill`. Use `*` to authorize everything (rarely a good idea).
 
-Whatever your runtime calls "system prompt" or "preamble", paste the contents of `openwar.md` in.
+Body sections: **Objective**, **Deliverables**, **Constraints**, **Tools required**, **Notes / unknowns**.
 
-## Why does this exist
+Validate a brief without running it:
 
-Default agent behavior (eager, sycophantic, prone to surprise actions) produces bad outcomes for serious work. You ship the wrong thing because the agent didn't confirm what you meant. You discover paid API spend you didn't authorize. You get "I'd be happy to help you with that!" instead of an actual answer.
+```bash
+openwar validate brief.md
+```
+
+## Still want just the system prompt?
+
+Paste [`openwar.md`](./openwar.md) into your agent's system prompt. The framework remains a single markdown file. You lose enforcement (the model is on the honor system), but you keep the behavior overlay.
+
+### Claude Code
+
+```bash
+mkdir -p ~/.claude
+curl -fsSL https://raw.githubusercontent.com/pythonluvr/openwar/main/openwar.md >> ~/.claude/CLAUDE.md
+```
+
+### Cursor
+
+Settings → Rules for AI → paste the contents of `openwar.md`.
+
+### War Room
 
-OpenWar replaces those defaults with the behavior of a senior peer. The agent reads your brief, says "here's what I heard, confirm?", and waits. It writes like an adult. It stops when it hits something it can't resolve instead of guessing. It tells you when something is outside what you asked for.
+War Room ships OpenWar as its default framework. v0.5+ adopts the runtime; earlier versions used the system prompt only.
 
-It's not magic. It's a system prompt. But it's a system prompt that's been battle-tested across thousands of real freelance / dev / creative tasks and refined to remove the failure modes that kept showing up.
+## Why both
 
-## Variants
+Behavioral overlays are easy to ignore. A model that's been told "always produce a Confirmation Summary" will sometimes skip it under context pressure or specific phrasing. The runtime catches the skip and asks the model to restate.
 
-The default is `openwar.md`, the full framework with all phases, hard rules, and triggers. Future variants will live in [`variants/`](./variants/):
+System prompts cost nothing to install and work with any runtime. The runtime is heavier, but it actually enforces the rules.
 
-- `openwar-strict.md`: adds aggressive confirmation gating; useful for high-stakes / production work
-- `openwar-light.md`: drops the pre-mortem trigger and brief format requirement; useful for casual chat / quick questions
+## Versioning
 
-(Empty for now, ships when stable.)
+Current: **v0.2.0** (runtime + framework doc).
 
-## Templates
+- v0.2: runtime, CLI, BYOK adapters for Anthropic / OpenAI / Gemini / Grok / OpenAI-compat.
+- v0.3: CLI-bridge adapters (claude-cli, codex-cli), MCP tool calling.
+- v0.4: multi-agent / boardroom orchestration.
 
-[`templates/brief.md`](./templates/brief.md) is a reference brief in OpenWar's format. Copy it when starting new tasks; the frontmatter fields drive how the agent gates execution.
+Framework doc is versioned with the package. Drop-in upgrades preserve compatibility within a major version; major bumps may rename phases or change the brief format.
 
 ## License
 
-[MIT](./LICENSE). Use it, modify it, fork it, ship your own variants, paste it into commercial products. No obligations beyond keeping the copyright notice.
+[MIT](./LICENSE).
 
 ## Authorship
 
-OpenWar is the framework that ships inside [War Room](https://github.com/pythonluvr/war-room), authored over many iterations of running real agent work. This standalone repo exists so people who don't use War Room can still adopt the framework.
+OpenWar is the framework that ships inside [War Room](https://github.com/pythonluvr/war-room), authored across many iterations of running real agent work. This standalone repo exists so people who don't use War Room can still adopt the framework.
 
-Issues + PRs welcome.
+Issues and PRs welcome.

bin/openwar

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// Resolves whether to run compiled dist (preferred) or tsx-compile src on the
+// fly (for development inside the repo before `npm run build` has run).
+
+import { existsSync } from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { dirname, join, resolve } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(here, "..");
+const dist = join(repoRoot, "dist", "cli.js");
+const srcCli = join(repoRoot, "src", "cli.ts");
+
+async function loadCli() {
+  if (existsSync(dist)) {
+    return await import(pathToFileURL(dist).href);
+  }
+  if (existsSync(srcCli)) {
+    try {
+      const tsx = await import("tsx/esm/api");
+      tsx.register();
+      return await import(pathToFileURL(srcCli).href);
+    } catch {
+      process.stderr.write(
+        "openwar: dist/cli.js not found and tsx is not installed. Run `npm install` and `npm run build`.\n",
+      );
+      process.exit(1);
+    }
+  }
+  process.stderr.write("openwar: cannot locate cli (no dist/cli.js or src/cli.ts).\n");
+  process.exit(1);
+}
+
+const mod = await loadCli();
+if (typeof mod.main !== "function") {
+  process.stderr.write("openwar: cli module did not export main().\n");
+  process.exit(1);
+}
+try {
+  const code = await mod.main(process.argv.slice(2));
+  process.exit(code ?? 0);
+} catch (err) {
+  process.stderr.write(`openwar: ${(err && err.message) || err}\n`);
+  process.exit(1);
+}

examples/README.md

@@ -0,0 +1,44 @@
+# OpenWar example briefs
+
+Two reference briefs you can run end-to-end against any configured adapter.
+
+## creative-brief.md
+
+A copywriting task with gated execution. Demonstrates:
+
+- Frontmatter with `scope_locked: false` and `mode: gated`.
+- An `authorized_costs: [generation_credits]` pre-approval so the agent does not flag every word it produces as destructive.
+- Soft constraints expressed in plain language (no em dashes, no filler openers).
+
+Run it:
+
+```bash
+npx openwar run examples/creative-brief.md --adapter anthropic
+```
+
+In gated mode the runner pauses after each step. Press Enter or type `ok` to continue. Type `done` to stop early.
+
+## engineering-brief.md
+
+A code task with auto-pilot execution and a locked scope. Demonstrates:
+
+- `scope_locked: true` so out-of-scope additions get refused without renegotiation.
+- `mode: auto` so the agent moves through clean steps without waiting on the operator.
+- `authorized_costs: [filesystem_write]` so writes do not trip the destructive flag, but git pushes, deploys, and process kills still do.
+
+Run it:
+
+```bash
+export OPENAI_API_KEY=sk-...
+npx openwar run examples/engineering-brief.md --adapter openai --model gpt-4o
+```
+
+## Inspecting after the run
+
+```bash
+openwar list                          # show recent sessions
+openwar inspect <brief_id>            # show session metadata
+openwar inspect <brief_id> --transcript   # full back-and-forth
+```
+
+Sessions persist to `~/.openwar/sessions/`. Resume with `openwar resume <brief_id>`.

examples/creative-brief.md

@@ -0,0 +1,34 @@
+---
+project: launch-anthem
+brief_id: 2026-01-15-A1
+scope_locked: false
+mode: gated
+authorized_costs:
+  - generation_credits
+---
+
+# Objective
+
+Draft three competing 30-second voiceover scripts for a product launch anthem. Tone should land between "we built this" pride and "you are seen" warmth. The product is a self-hosted journaling app for people who write longhand. The audience is everyone who has tried five productivity tools and quit them.
+
+# Deliverables
+
+- Three voiceover scripts of 60 to 80 words each
+- For each script: a one-line tonal description and a single sentence about who it targets
+- A recommendation at the end with which to film first and why
+
+# Constraints
+
+- No em dashes in any of the output
+- No filler openers like "in a world where" or "what if"
+- Do not write more than three options; do not pad with a fourth weaker variant
+- Stay vendor-neutral; do not name competing products
+
+# Tools required
+
+- None beyond text generation
+
+# Notes / unknowns
+
+- The product name has not been finalized. Use the placeholder "the app" instead of inventing one.
+- A second pass for VO timing markers is out of scope for this brief.