warden AGENTS.md

AGENTS.md — Warden

What this project is

Warden is a constitutional runtime for AI agents, exposed as an MCP server. Thesis: agents cannot mint their own authority. Identity is granted (atomic reservation), work moves in typed envelopes with loud rejection, promotion is human-only (the approval capability does not exist agent-side), and history is an append-only hash-chained ledger that cannot be rewritten silently.

Read README.md first — it is the constitution. Every change must strengthen or demonstrate one of the four Articles. If a change weakens an Article, stop and ask.

Hard rules

• Never add an MCP tool that approves, promotes, or closes work. The absence of that tool is the core argument of the project.
• Never make the ledger mutable, truncatable, or optional. Violations stay on the record forever.
• Rejections must be explicit and descriptive — echo what was attempted, what is allowed, and that the attempt was recorded. No silent failures, no coerced defaults.
• Zero heavy dependencies. Current stack: Node 22+, ESM, @modelcontextprotocol/sdk, zod. State = JSON file; ledger = JSONL. Do not introduce databases, frameworks, or build steps without an explicit request.
• Do not reference private companies, clients, internal ecosystems, or internal task systems in code, comments, docs, or commit messages. Public tools and interoperability targets may be named only when materially relevant to Warden. This is a standalone personal open-source project (Apache-2.0).

Layout

• src/ledger.mjs — hash-chained append-only ledger (Article IV)
• src/warden.mjs — core primitives and violation classes (Articles I–III)
• src/server.mjs — MCP stdio server; agent-facing tools only
• bin/warden-cli.mjs — human-side gate + replay (never reachable via MCP)
• demo/cheat.mjs — executable demo: every violation class, then the honest path, then ledger tampering caught by chain verification

Conventions

• Small, single-purpose commits with descriptive messages; commit after every working increment (commit history is part of the hackathon evidence).
• Any new violation class gets: a rule name in SCREAMING_SNAKE, a ledger event, a loud rejection message, and coverage in demo/cheat.mjs.
• Tests: plain node scripts under test/ (no framework). npm test must pass before any commit.
• Keep tool descriptions in server.mjs normative — they tell the agent what is forbidden and that violations are recorded. They are part of the constitution, not decoration.