Feature request: RFC 2119 keyword enforcement layer for CLAUDE.md instructions

Summary

CLAUDE.md instructions today are natural language interpreted probabilistically by the LLM. This proposes adopting RFC 2119 keywords (MUST, SHOULD, MAY, etc.) as a formal vocabulary with mechanical enforcement by the harness — not just as prompt conventions.

Problem

All instructions in CLAUDE.md are treated equally — the LLM does its best to follow them, but there's no distinction between hard constraints and soft preferences. "Never push to main" and "prefer small commits" carry the same enforcement mechanism: hope.

In multi-agent workflows this gets worse: parent agents delegate to subagents, each with their own instruction context. There's no way to express or enforce that certain constraints are inviolable vs best-effort.

Proposal

Add an optional constraint parser to the CLAUDE.md processing pipeline that recognizes RFC 2119 keywords and routes them to appropriate enforcement:

| Keyword | Semantics | Enforcement |
|---------|-----------|-------------|
| MUST / MUST NOT | Hard constraint | Pre/post tool-call gate (harness blocks violations) |
| SHOULD / SHOULD NOT | Strong preference | Included in prompt with high weight; violations logged |
| MAY | Permitted capability | Informational — agent knows it can, no obligation |

How it would work

1. Parse: On CLAUDE.md load, extract sentences containing RFC 2119 keywords (uppercase = formal, lowercase = prose)
2. Classify: Map each to a constraint type + subject (tool call, file path, git operation, etc.)
3. Enforce MUST/MUST NOT: Register as pre-execution checks in the tool pipeline (similar to hooks, but declarative and portable)
4. Surface SHOULD/MAY: Pass to the LLM as prioritized context

Example CLAUDE.md

## Constraints

You MUST NOT commit files matching `*.env` or `credentials.*`.
You MUST run `npm test` before creating any commit.
You SHOULD prefer editing existing files over creating new ones.
You SHOULD NOT add dependencies without checking existing package.json first.
You MAY use parallel tool calls for independent operations.

The first two become hard gates — the harness blocks the action and surfaces an error. The rest inform the LLM's behavior with clear priority.

Value in multi-agent / agentic workflows

• Composability: Parent agents impose MUST constraints on subagents that the subagent's LLM cannot override
• Auditability: Log which constraints were evaluated per action, which passed, which blocked — essential for enterprise use
• Conflict resolution: When instructions from different sources conflict (project CLAUDE.md vs user CLAUDE.md vs memory), keyword level provides a clear tiebreaker
• Separation of concerns: Harness enforces mechanical constraints; LLM focuses on judgment calls

Relation to existing features

This is complementary to hooks — hooks are imperative shell commands; this would be declarative constraints. Think of it as hooks for people who don't want to write bash. It could even compile down to hooks internally.

Alternatives considered

• Just use hooks: Works for MUST/MUST NOT but requires shell scripting, isn't portable, and doesn't help with SHOULD/MAY gradation
• Better prompting: Caps and emphasis already help, but the LLM can still violate hard constraints — there's no mechanical backstop
• Custom lint rules: Per-project but not standardized, no integration with the tool execution pipeline