Skip to main content
Discuss a project日本語

Open-source declaration checker

Agent Role Contracts

Check an AI coding team’s role, write-scope, and reviewer declarations for conflicts before any agent runs. It reads JSON files offline and reports declaration conflicts with specific error codes.

Try the checkerView on GitHub
Release
0.1.0 on npm
License
MIT
Runtime
Node.js 22.5 or later
Network
Only to install. Checks run offline.

This page describes the published 0.1.0 release only. Newer work on the GitHub main branch is unreleased and is not what npm install gives you.

A scope conflict, caught before anyone writes

The team declaration says the implementer may write under src/. The task asks for a file in secrets/. The checker compares the two and refuses.

ExampleDeclared in the bundle
role: implementer
allowed_write_scopes: ["src/**"]
ExampleRequested by the task
inputs.scope: "secrets/production.txt"
ExampleExit code 1. The declarations disagree.
FAIL: explain (declarations only; execution NOT authorized)
TASK_WRITE_SCOPE_OUTSIDE_AUTHORITY task/inputs/scope:
  Task scope is outside declared write scopes for role implementer: secrets/production.txt

Change the task scope back to src/example.mjs and the same command prints PASS.

Three checks it runs on your declarations

Each result below comes from a fixture shipped in the 0.1.0 package.

  1. AUTHORITY_CONTRADICTION

    A role cannot be read-only and allowed to write

    A role that lists filesystem.write.scoped as both allowed and prohibited, or as read-only, is flagged.

  2. SELF_REVIEW_DECLARED

    The implementer cannot also be the reviewer

    A route that names one role as both implementer and reviewer is rejected, along with reviewers that are not read-only.

  3. ROLE_REFERENCE_UNKNOWN

    Roles must refer to roles that exist

    A relation that points to a role missing from the bundle, such as ghost, is reported instead of ignored.

Run your first check

Install the released package into an empty folder and check the bundled starter fixtures.

mkdir agent-role-contracts-first-check
cd agent-role-contracts-first-check
npm init --yes
npm install --ignore-scripts @netsujo/agent-role-contracts@0.1.0
npx --no-install agent-role-contracts explain \
  --bundle node_modules/@netsujo/agent-role-contracts/examples/starter-bundle.json \
  --task node_modules/@netsujo/agent-role-contracts/examples/starter-task.json \
  --format text

Expected output (Example, excerpt)

PASS: explain (declarations only; execution NOT authorized)
Accountable: implementer
Reviewers: reviewer
Human approval required: true
  • validate checks the bundle alone.
  • explain also checks one task’s write scope.
  • handoff checks a handoff document you supply separately.

Exit codes: 0 means PASS, 1 means a rule was violated, 2 means a CLI or file problem with no verdict.

To see a FAIL, swap starter-task.json for starter-task-outside-scope.json.

What a PASS means

It does mean

  • The declarations you supplied are consistent under the rules this version applies.
  • Only checks performed by the selected command count: validate covers the bundle; explain adds the supplied task; handoff also checks the supplied handoff.

It does not mean

  • Anything was executed, sandboxed, or enforced. It is not an agent runner or a sandbox.
  • Anyone’s identity or any evidence was verified, or the filesystem was scanned.
  • An agent’s output matches a schema, or a merge or deploy is approved.
  • The work is safe. Output of the command always says execution is NOT authorized.

Docs, package, and the longer explanation