Add iso-capabilities

Author: CharGrnmn

.github/workflows/ci.yml

@@ -59,6 +59,9 @@ jobs:
           - workspace: "@razroo/iso-contract"
             node: "20.6.0"
             extra: ""
+          - workspace: "@razroo/iso-capabilities"
+            node: "20.6.0"
+            extra: ""
           - workspace: "@razroo/iso-trace"
             node: "20.6.0"
             extra: ""
@@ -179,6 +182,12 @@ jobs:
           node packages/iso-contract/dist/cli.js validate jobforge.tracker-row --contracts packages/iso-contract/examples/jobforge-contracts.json --input @packages/iso-contract/examples/tracker-row.json
           node packages/iso-contract/dist/cli.js render jobforge.tracker-row --contracts packages/iso-contract/examples/jobforge-contracts.json --input @packages/iso-contract/examples/tracker-row.json --format tsv
 
+      - name: iso-capabilities example check/render
+        run: |
+          node packages/iso-capabilities/dist/cli.js list --policy packages/iso-capabilities/examples/jobforge-capabilities.json
+          node packages/iso-capabilities/dist/cli.js check applicant --policy packages/iso-capabilities/examples/jobforge-capabilities.json --tool browser --mcp geometra --command "npx job-forge merge" --filesystem write --network restricted
+          node packages/iso-capabilities/dist/cli.js render applicant --policy packages/iso-capabilities/examples/jobforge-capabilities.json --target opencode
+
       - 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-capabilities-release.yml

@@ -0,0 +1,48 @@
+name: iso-capabilities Release to npm
+
+on:
+  release:
+    types: [published]
+
+defaults:
+  run:
+    working-directory: packages/iso-capabilities
+
+jobs:
+  publish:
+    if: startsWith(github.ref_name, 'iso-capabilities-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-capabilities-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 eleven Razroo tools that together make
+Workspaces monorepo (npm) housing twelve 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).
@@ -61,6 +61,11 @@ cross-package compositions and the decouplings that are deliberate.
   artifact contracts for agent workflows: validate, parse, and render
   JSON/TSV/markdown records without model calls. TypeScript, `tsc` →
   `dist/`. Tests via `node --test --import tsx tests/*.test.ts`.
+- `packages/iso-capabilities` — `@razroo/iso-capabilities`.
+  Deterministic role capability policies for agent workflows: resolve,
+  check, and render tool/MCP/command/filesystem/network permissions
+  without model calls. TypeScript, `tsc` → `dist/`. Tests via
+  `node --test --import tsx tests/*.test.ts`.
 
 ## Conventions
 

INTEGRATIONS.md

@@ -1,6 +1,6 @@
 # Integrations
 
-This repo ships eleven packages that **work on their own** but are **designed
+This repo ships twelve 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:
 
@@ -139,6 +139,18 @@ asking the model to remember exact column order.
 
 ---
 
+## 9. `iso-capabilities` ← deterministic role capability policy for domain packages — **DONE**
+
+Introduced as a standalone package. `iso-capabilities` does not import
+JobForge, `iso-harness`, or any other domain package; it provides the
+on-disk JSON role catalog format and checker that domain packages can
+share. JobForge-style examples cover orchestrator, applicant, and
+verifier roles, but the package remains generic: resolve inheritance,
+check tool/MCP/command/filesystem/network requests, and render compact
+target guidance without asking the model to remember a permission matrix.
+
+---
+
 ## Design questions that are *not* open integrations
 
 The following look like integrations but are deliberately decoupled —
@@ -170,3 +182,8 @@ don't "fix" them without a conversation first.
   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.
+- **`iso-capabilities` does not mutate harness permissions directly.**
+  It emits an executable policy/checker plus compact target guidance.
+  Native enforcement should stay additive and harness-specific; where a
+  harness cannot enforce a field, pair the policy with `iso-trace` /
+  `iso-guard` audits instead of implying a stronger guarantee.

README.md

@@ -10,9 +10,9 @@
 authored source fans out to every coding harness (Cursor, Claude Code,
 Codex, OpenCode) and stays legible across model tiers (frontier models down
 to 7B local models). The repo now covers the full loop: build portable
-harness files, route models, replay evals, parse production traces, audit
-runtime policy, validate artifact contracts, and persist local workflow
-truth. The only narrower surface is `iso-trace model-score`, which still
+harness files, route models, replay evals, parse production traces, scope
+role capabilities, audit runtime policy, validate artifact contracts, and
+persist local workflow truth. The only narrower surface is `iso-trace model-score`, which still
 depends on transcripts exposing stable model metadata.
 
 Today, agent workflow reliability is fragmented on three axes:
@@ -27,11 +27,11 @@ Today, agent workflow reliability is fragmented on three axes:
    unstructured rationale all drop silently at 7B. You don't find out
    until the agent misbehaves in production.
 3. **Runtime fragmentation.** Workflows rely on fragile prompt prose for
-   fan-out limits, output shape, duplicate checks, and "what already
-   happened." Those invariants belong in deterministic local packages,
+   fan-out limits, role permissions, output shape, duplicate checks, and
+   "what already happened." Those invariants belong in deterministic local packages,
    not in repeatedly re-tokenized instructions.
 
-Eleven packages solve that in one pipeline with runtime control and a
+Twelve packages solve that in one pipeline with runtime control and a
 feedback loop:
 
 - **Four build-time tools** turn your authored source into every harness's file layout:
@@ -41,9 +41,11 @@ feedback loop:
   [`@razroo/iso-route`](./packages/iso-route) compiles *one model policy* into each harness's config.
 - **One wrapper** runs the whole build chain:
   [`@razroo/iso`](./packages/iso) chains the above into a single `iso build`.
-- **Three runtime-control libraries** handle durable execution, artifact shape, and operational truth:
+- **Four runtime-control libraries** handle durable execution, role capabilities, artifact shape, and operational truth:
   [`@razroo/iso-orchestrator`](./packages/iso-orchestrator) provides resumable
   steps, keyed mutexes, and bounded fan-out for side-effectful agent workflows,
+  [`@razroo/iso-capabilities`](./packages/iso-capabilities) resolves,
+  checks, and renders role-level tool/MCP/command/filesystem/network policy,
   [`@razroo/iso-contract`](./packages/iso-contract) validates, parses, and
   renders structured workflow artifacts, and [`@razroo/iso-ledger`](./packages/iso-ledger)
   records append-only domain events with idempotency keys, queries,
@@ -62,6 +64,7 @@ feedback loop:
   └────────────────────┘           └───────────────────┘           └─────────────────┘               │ .opencode/agents/*    │                    which rules ever fired,
                                                                                                      │ settings.json         │                    regression-fixture mining
                                                                                                      │                      │    iso-guard ─▶  policy pass / fail
+                                                                                                     │                      │    iso-capabilities ─▶ role permission policy
   ┌────────────────────┐                                                                             │ .codex/config.toml    │
   │ models.yaml        │ ───────────────────── iso-route build ─────────────────────────────────────▶│ opencode.json         │
   │ (roles + fallback) │                                                                             │ .mcp.json             │
@@ -108,6 +111,8 @@ the repo now supports a tighter loop:
 
 - `isolint` rewrites authored prose into smaller-model-safe instructions.
 - `iso-route` lets you pin cheaper or local roles without forking prompts.
+- `iso-capabilities check/render` keeps role permission matrices local
+  instead of repeating tool/MCP/filesystem boundaries in prompts.
 - `iso-trace model-score` catches tool-schema failures that weaker routes
   tend to surface first on Claude Code, Codex, and OpenCode.
 - `iso-trace export-fixture --runner <name>` turns a real failure into an
@@ -127,6 +132,10 @@ of the prompt:
 
 - `iso-orchestrator` persists resumable `step()` results, mutexes work by
   entity key, and bounds fan-out for side-effectful workflows.
+- `iso-capabilities` makes role boundaries executable: resolve inherited
+  tool/MCP/command/filesystem/network policy, check proposed actions, and
+  render compact harness guidance without asking a model to remember a
+  permission matrix.
 - `iso-contract` makes artifact shape executable: validate records, parse
   existing TSV/markdown/JSON, and render canonical output without asking a
   model to remember delimiters.
@@ -213,6 +222,12 @@ of the prompt:
   and markdown table rows so domain packages can keep artifact formats
   out of prompt prose.
 
+- **[`packages/iso-capabilities`](./packages/iso-capabilities)** — [`@razroo/iso-capabilities`](https://www.npmjs.com/package/@razroo/iso-capabilities)
+  Deterministic role capability policies for agent workflows. Loads JSON
+  role catalogs, resolves inheritance, checks proposed tool/MCP/command/
+  filesystem/network access, and renders compact target guidance so
+  domain packages can keep permission matrices out of prompt prose.
+
 - **[`packages/iso-orchestrator`](./packages/iso-orchestrator)** — [`@razroo/iso-orchestrator`](https://www.npmjs.com/package/@razroo/iso-orchestrator)
   Durable orchestration primitives for the runtime layer above a single
   agent session. Persists workflow state to local disk, memoizes
@@ -346,6 +361,15 @@ iso-contract render jobforge.tracker-row --contracts contracts.json --input @row
 iso-contract parse jobforge.tracker-row --contracts contracts.json --format tsv --input "812	2026-04-26	Example Labs	Staff Agent Engineer	Applied	4.2/5	yes	[812](reports/812-example-labs-2026-04-26.md)	Submitted"
 ```
 
+### `@razroo/iso-capabilities` — what may this role do?
+
+```bash
+iso-capabilities list --policy capabilities.json
+iso-capabilities explain applicant --policy capabilities.json
+iso-capabilities check applicant --policy capabilities.json --tool browser --mcp geometra --command "npx job-forge merge" --filesystem write --network restricted
+iso-capabilities render applicant --policy capabilities.json --target opencode
+```
+
 ## Layout
 
 ```
@@ -363,7 +387,8 @@ iso/
     ├── iso-trace/        # parse + query real agent transcripts (observability)
     ├── iso-guard/        # deterministic runtime policy checks over events
     ├── iso-ledger/       # append-only operational event/state ledger
-    └── iso-contract/     # deterministic artifact contracts
+    ├── iso-contract/     # deterministic artifact contracts
+    └── iso-capabilities/ # deterministic role capability policy
 ```
 
 ## Build & test
@@ -381,6 +406,7 @@ npm --workspace @razroo/iso-trace run example   # iso-trace stats on the bundled
 npm --workspace @razroo/iso-guard run test      # iso-guard policy engine tests
 npm --workspace @razroo/iso-ledger run test     # iso-ledger event/state tests
 npm --workspace @razroo/iso-contract run test   # iso-contract artifact contract tests
+npm --workspace @razroo/iso-capabilities run test # iso-capabilities policy tests
 
 # Target a single package
 npm run build --workspace @razroo/isolint
@@ -416,7 +442,7 @@ build, and `npm publish --provenance`.
 ## End-to-end example
 
 [`examples/pipeline/`](./examples/pipeline) is an executable demonstration
-that exercises **seven of the eleven packages end-to-end** in one `npm run
+that exercises **seven of the twelve 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
@@ -435,7 +461,7 @@ 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`, `iso-trace`, `iso-route`, `iso-guard`, `iso-ledger`, and `iso-contract`
+`iso-harness`, `iso`, `iso-eval`, `iso-trace`, `iso-route`, `iso-guard`, `iso-ledger`, `iso-contract`, and `iso-capabilities`
 CLIs. This guards against packaging regressions that workspace-only tests can
 miss.
 

package-lock.json

@@ -0,0 +1,11 @@
+# @razroo/iso-capabilities
+
+## 0.1.0
+
+### Minor Changes
+
+- Add iso-capabilities for deterministic role capability policies, checks, and target render output.
+
+## 0.0.0
+
+- Initial unreleased scaffold.

packages/iso-capabilities/CHANGELOG.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 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.