Add iso-guard package

Author: CharGrnmn

.github/workflows/ci.yml

@@ -56,6 +56,9 @@ jobs:
           - workspace: "@razroo/iso-trace"
             node: "20.6.0"
             extra: ""
+          - workspace: "@razroo/iso-guard"
+            node: "20.6.0"
+            extra: ""
           - workspace: "@razroo/agentmd"
             node: "22.0.0"
             extra: ""
@@ -148,6 +151,18 @@ jobs:
       - name: iso-trace example stats
         run: node packages/iso-trace/dist/cli.js stats --source packages/iso-trace/examples/sample-session.jsonl
 
+      - name: iso-guard example audit
+        run: |
+          cat > /tmp/iso-guard-events.json <<'JSON'
+          [
+            { "type": "tool_call", "name": "geometra_disconnect", "data": { "round": 1 } },
+            { "type": "tool_call", "name": "task", "data": { "round": 1, "mode": "apply" } },
+            { "type": "tool_call", "name": "job-forge-merge" },
+            { "type": "tool_call", "name": "job-forge-verify" }
+          ]
+          JSON
+          node packages/iso-guard/dist/cli.js audit packages/iso-guard/examples/jobforge-apply.yaml --events /tmp/iso-guard-events.json
+
       - name: iso-route example build (dry-run + verify)
         run: node packages/iso-route/dist/cli.js build packages/iso-route/examples/models.yaml --out /tmp/iso-route-smoke --dry-run --verify-models
 

.github/workflows/iso-guard-release.yml

@@ -0,0 +1,48 @@
+name: iso-guard Release to npm
+
+on:
+  release:
+    types: [published]
+
+defaults:
+  run:
+    working-directory: packages/iso-guard
+
+jobs:
+  publish:
+    if: startsWith(github.ref_name, 'iso-guard-v')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      checks: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'npm'
+
+      - name: Set version from release tag
+        run: |
+          VERSION="${GITHUB_REF_NAME#iso-guard-v}"
+          echo "VERSION=$VERSION" >> $GITHUB_ENV
+
+      - name: Verify required CI passed for release commit
+        uses: ./.github/actions/verify-release-gate
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Verify package.json version matches release tag
+        run: npm run release:check-source -- "$VERSION"
+
+      - name: Install (workspace root)
+        run: npm ci
+        working-directory: .
+
+      - name: Publish to npm (with provenance)
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

CLAUDE.md

@@ -1,6 +1,6 @@
 # iso — monorepo
 
-Workspaces monorepo (npm) housing eight Razroo tools that together make
+Workspaces monorepo (npm) housing nine Razroo tools that together make
 AI-agent harnesses *isomorphic* — the same authored source producing the
 same behavior across every coding harness (Cursor, Claude Code, Codex,
 OpenCode) and every model tier (frontier → 7B local).
@@ -31,9 +31,8 @@ cross-package compositions and the decouplings that are deliberate.
 **Wrapper:**
 
 - `packages/iso` — `@razroo/iso`. Chains `agentmd → isolint →
-  iso-harness` behind one CLI. Plain ESM `.mjs`. Depends on the sibling
-  packages via workspace protocol. (iso-route is *not* composed yet — see
-  `INTEGRATIONS.md` item #2.)
+  iso-route → iso-harness` behind one CLI when `models.yaml` exists.
+  Plain ESM `.mjs`. Depends on the sibling packages via workspace protocol.
 
 **Feedback (post-deploy):**
 
@@ -43,6 +42,9 @@ cross-package compositions and the decouplings that are deliberate.
 - `packages/iso-trace` — `@razroo/iso-trace`. Parses Claude Code JSONL
   sessions into a normalized event model for local observability. Zero
   upload. TypeScript.
+- `packages/iso-guard` — `@razroo/iso-guard`. Deterministic runtime
+  policy checks over normalized event streams and `iso-trace export`
+  JSON/JSONL. TypeScript.
 
 **Runtime control:**
 

INTEGRATIONS.md

@@ -1,6 +1,6 @@
 # Integrations
 
-This repo ships eight packages that **work on their own** but are **designed
+This repo ships nine packages that **work on their own** but are **designed
 to compose**. The planned cross-package compositions listed here are already
 shipped, so this file now serves as:
 
@@ -102,6 +102,18 @@ resolved role map — plus fixture export output from the trace loop.
 
 ---
 
+## 6. `iso-guard` ← consumes `iso-trace export` JSON/JSONL — **DONE**
+
+Introduced with `@razroo/iso-guard`'s initial release. The guard package
+accepts either small normalized event arrays or `iso-trace export
+<session> --format json|jsonl` output, flattens those events, and
+evaluates deterministic runtime policy rules (`max-per-group`,
+`require-before`, `require-after`, `forbid-text`, `no-overlap`). This
+keeps enforcement outside the prompt/MCP surface while still letting a
+project audit real agent behavior after a run.
+
+---
+
 ## Design questions that are *not* open integrations
 
 The following look like integrations but are deliberately decoupled —
@@ -128,3 +140,8 @@ don't "fix" them without a conversation first.
   `build --verify-models` exist, but the default `build` path still
   validates provider names, not model IDs. Asking a live catalog is an
   opt-in check, not part of the baseline transpile step.
+- **`iso-guard` is not an MCP server.** It is a CLI/library that reads
+  event files and emits compact pass/fail output. If a domain package
+  wants in-loop preflight, it should call the CLI and feed only the
+  concise result back to the agent, not load the whole policy into the
+  prompt prefix.

README.md

@@ -25,7 +25,7 @@ Today, writing agent instructions is fragmented on two axes:
    unstructured rationale all drop silently at 7B. You don't find out
    until the agent misbehaves in production.
 
-Eight packages solve that in one pipeline with a control layer and feedback loop:
+Nine packages solve that in one pipeline with a control layer and feedback loop:
 
 - **Four build-time tools** turn your authored source into every harness's file layout:
   [`@razroo/agentmd`](./packages/agentmd) validates *structure*,
@@ -37,9 +37,10 @@ Eight packages solve that in one pipeline with a control layer and feedback loop
 - **One orchestration library** handles durable runtime control:
   [`@razroo/iso-orchestrator`](./packages/iso-orchestrator) provides resumable
   steps, keyed mutexes, and bounded fan-out for side-effectful agent workflows.
-- **Two feedback tools** close the loop after deploy:
+- **Three feedback tools** close the loop after deploy:
   [`@razroo/iso-eval`](./packages/iso-eval) scores *did the agent complete the task?* and
-  [`@razroo/iso-trace`](./packages/iso-trace) parses production transcripts to show *what the agent actually did*.
+  [`@razroo/iso-trace`](./packages/iso-trace) parses production transcripts to show *what the agent actually did*,
+  while [`@razroo/iso-guard`](./packages/iso-guard) enforces operational policies against those event streams.
 
 ```
                 authoring                          build                               output                        feedback
@@ -49,6 +50,7 @@ Eight packages solve that in one pipeline with a control layer and feedback loop
   │                    │   render  │ load-bearing why  │           │                 │               │ .cursor/rules/*       │    iso-trace ──▶  production events,
   └────────────────────┘           └───────────────────┘           └─────────────────┘               │ .opencode/agents/*    │                    which rules ever fired,
                                                                                                      │ settings.json         │                    regression-fixture mining
+                                                                                                     │                      │    iso-guard ─▶  policy pass / fail
   ┌────────────────────┐                                                                             │ .codex/config.toml    │
   │ models.yaml        │ ───────────────────── iso-route build ─────────────────────────────────────▶│ opencode.json         │
   │ (roles + fallback) │                                                                             │ .mcp.json             │
@@ -99,6 +101,8 @@ the repo now supports a tighter loop:
   tend to surface first on Claude Code, Codex, and OpenCode.
 - `iso-trace export-fixture --runner <name>` turns a real failure into an
   `iso-eval` suite you can replay across shipped runners.
+- `iso-guard audit` checks whether a real run obeyed operational policy
+  without turning those rules into more prompt tokens.
 
 ## Packages
 
@@ -158,6 +162,13 @@ the repo now supports a tighter loop:
   transcripts do not yet expose stable model metadata. Zero upload —
   everything is local reads and user-controlled output.
 
+- **[`packages/iso-guard`](./packages/iso-guard)** — [`@razroo/iso-guard`](https://www.npmjs.com/package/@razroo/iso-guard)
+  Deterministic runtime policy checks for agent workflows. Reads normalized
+  event streams or `iso-trace export` JSON/JSONL and verifies invariants
+  such as bounded fan-out, cleanup-before-dispatch, required follow-up
+  commands, no overlapping same-key work, and prompt secret redaction.
+  No model calls, no MCP server, and no injected prompt overhead.
+
 - **[`packages/iso-orchestrator`](./packages/iso-orchestrator)** — `@razroo/iso-orchestrator`
   Durable orchestration primitives for the runtime layer above a single
   agent session. Persists workflow state to local disk, memoizes
@@ -261,6 +272,15 @@ iso-trace export <id> --format jsonl --redact > session.jsonl
 iso-trace export-fixture <id> --out fixtures/my-task --runner codex --edit-checks exists-only --run
 ```
 
+### `@razroo/iso-guard` — did the run obey policy?
+
+```bash
+iso-guard audit guard.yaml --events session.json
+iso-guard audit guard.yaml --events session.jsonl --json
+iso-guard verify guard.yaml --events session.json --fail-on warn
+iso-guard explain guard.yaml
+```
+
 ## Layout
 
 ```
@@ -275,7 +295,8 @@ iso/
     ├── iso-route/        # one model policy → per-harness config
     ├── iso-orchestrator/ # durable runtime control above one agent session
     ├── iso-eval/         # behavioral eval on the produced harness
-    └── iso-trace/        # parse + query real agent transcripts (observability)
+    ├── iso-trace/        # parse + query real agent transcripts (observability)
+    └── iso-guard/        # deterministic runtime policy checks over events
 ```
 
 ## Build & test
@@ -290,6 +311,7 @@ npm run test:pack           # pack local tarballs and smoke installed CLIs
 npm run test:pipeline       # end-to-end demo (agentmd → isolint → iso-harness)
 npm --workspace @razroo/iso-eval  run example   # iso-eval against the bundled example suite
 npm --workspace @razroo/iso-trace run example   # iso-trace stats on the bundled sample transcript
+npm --workspace @razroo/iso-guard run test      # iso-guard policy engine tests
 
 # Target a single package
 npm run build --workspace @razroo/isolint
@@ -325,7 +347,7 @@ build, and `npm publish --provenance`.
 ## End-to-end example
 
 [`examples/pipeline/`](./examples/pipeline) is an executable demonstration
-that exercises **seven of the eight packages end-to-end** in one `npm run
+that exercises **seven of the nine packages end-to-end** in one `npm run
 test:pipeline` invocation: `agentmd lint` + `render` → `isolint lint` →
 `iso-route build` (from a bundled `models.yaml` that extends the
 `standard` preset) → `iso-harness build` (which consumes iso-route's
@@ -344,8 +366,9 @@ downstream repo would use.
 
 `npm run test:pack` goes one level further: it packs the local workspaces into
 tarballs, installs them into fresh temp projects, and smoke-tests the packaged
-`iso-harness`, `iso`, `iso-eval`, and `iso-trace` CLIs. This guards against
-packaging regressions that workspace-only tests can miss.
+`iso-harness`, `iso`, `iso-eval`, `iso-trace`, `iso-route`, and `iso-guard`
+CLIs. This guards against packaging regressions that workspace-only tests can
+miss.
 
 [`packages/iso-eval/examples/suites/echo-basic/`](./packages/iso-eval/examples/suites/echo-basic)
 is a runnable eval suite for the downstream side: a baseline workspace, a

package-lock.json

@@ -0,0 +1,11 @@
+# @razroo/iso-guard
+
+## 0.1.0
+
+### Minor Changes
+
+- Introduce `@razroo/iso-guard`, a deterministic CLI/library for auditing agent workflow events against machine-readable runtime policy without adding prompt or MCP token overhead.
+- Adds deterministic policy auditing over normalized event streams and
+  `iso-trace export` JSON/JSONL.
+- Supports `max-per-group`, `require-before`, `require-after`,
+  `forbid-text`, and `no-overlap` rules.

packages/iso-guard/CHANGELOG.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Razroo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.