You write the boundaries. Agents read them.

Title

Machine-Readable Context

Status

Working Specification

Format

Markdown (.md)

Version

v0.2.0

---
version: 1.0
enforcement: strict
---

# Boundaries
- Agents MAY read any file in `src/`
- Agents MUST NOT modify files in `src/core/auth/` without human review
- Agents MUST NOT run `npm publish`

# Context
The system is built on Next.js App Router. Do not use the Pages router.
Always use Tailwind CSS for styling. Do not write custom CSS.

# Verification
Before proposing a PR, agents MUST run:
`npm run lint` and `npm test`

A policy file in .policy/: frontmatter for the runtime, Markdown for people and models.

Capabilities

1. 1.3Machine-enforceable YAML frontmatter + Markdown body
2. 1.4allow / deny / require_approval actions
3. 1.5Condition operators (eq, neq, gt, gte, lt, lte, includes, in, notIn, exists, notExists, wildcard)
4. 1.6Scope targets: project, skill, agent, or department
5. 1.7OpenAI Codex adapter (execpolicy + guardian prompt export)
6. 1.8CLI for validate, check, read, init, install, sync, and list

---
name: project-guardrails
description: Hard boundaries for this repo
version: 1.0.0
scope: project
appliesTo: [all]
rules:
  - capability: file.write
    action: deny
    condition:
      field: { path: 'payload.path', op: 'includes', value: '.env' }
    reason: Never write .env or secret files

  - capability: package.install
    action: require_approval
    reason: New dependencies need approval

  - capability: npm.test
    action: allow
    reason: Tests can run without approval
---

## Forbidden
- Never commit `.env` files or any file containing secrets
- Never execute obfuscated shell commands

## Ask first
- Adding npm dependencies
- Modifying CI/CD pipelines

## Allowed
- Running `npm run typecheck` and `npm run test`
- Reading project documentation

Each frontmatter rule has a twin in the body: deny under ## Forbidden, require_approval under ## Ask first, allow under ## Allowed.

condition:
  field: { path: payload.path, op: includes, value: .env }

condition:
  and:
    - field: { path: payload.amount, op: gt, value: 1000 }
    - field: { path: constraints.environment, op: eq, value: production }

condition:
  or:
    - field: { path: workerId, op: eq, value: payment-bot }
    - field: { path: specialist, op: in, values: [frontend, backend] }

A field test, an and group and an or group.

Frontmatter / Scope fields

# .policy/POLICY.md  (scope: project)
package.install   require_approval
npm.test          allow

# skills/deploy/POLICY.md  (scope: skill)
package.install   deny

# combined for package.install
deny

$ git clone https://github.com/SidianLabs/POLICY.md.git && cd POLICY.md
$ npm install && npm run build
$ node bin/policy.js --help

$ node bin/policy.js check POLICY.md file.write --payload='{"path":".env"}'
deny  rule file.write
  Never write .env or secret files

$ node bin/policy.js check POLICY.md package.install
require_approval  rule package.install
  New dependencies need approval

$ node bin/policy.js check POLICY.md npm.test
allow  rule npm.test
  Tests can run without approval

Checking the docs example POLICY.md. The commands follow the reference below; the printed output is illustrative.

import { toCodexExecpolicy, toCodexGuardianPrompt } from '@sidianlabs/policy/adapters/codex';

const execpolicy = toCodexExecpolicy(manager.list());
const guardianPrompt = toCodexGuardianPrompt(manager.list());

Rules in, by capability / Illustrative

NON-GUARANTEES.md / Summary

Assumptions

1. A.1A host runtime must call the authorization engine. POLICY.md does not enforce itself.
2. A.2Write access to the policy file allows modification (no signature verification on installed policies).

Not guaranteed

1. N.1Default behavior is fail-open (allow when no rule matches).
2. N.2The OpenAI Codex adapter covers only command.run and network.* rules; other rule types are silently dropped.
3. N.3The specification is a working draft (v0.2.0), not a finalized industry standard.
4. N.4The package is not yet published to npm.