Governance files

Which file is which — and the difference between a file that gives advice and a file that gets enforced.

Steelmoth keeps its rules in several files, and they are not interchangeable. Some are read by agents as instructions, some are read by machines as policy, and some are background reference. The single most useful thing to know is which axis a file sits on: is it advice, or is it enforced?

The map

File	Who reads it	What it is
CLAUDE.md	Claude Code, every session	The 15 hard rules — agent-facing instructions, loaded automatically.
AGENTS.md	Codex & any repo-loading agent	The same intent as CLAUDE.md, the entry point that binds non-Claude agents.
engineering-standards/README.md	Agents, before any work	The index to the standards folder and its tier system.
ARCHITECTURE_INVARIANTS.md	Agents + the fitness tests	The numbered safety properties (INV-001…026). Prose and machine-checked.
PROTECTED_PATHS.md	Agents (human-readable)	The protected-path list — derived from the YAML, not the source.
AGENT_POLICY.yaml	Every checkpoint	The one canonical, machine-readable policy. The source of truth.
AGENT_DEV_GUIDELINES.md	Agents	The “what good work looks like” guide.
AGENT_DEV_PROCESS.md	Agents	The four-role development pipeline (Architect → Implementer → Reviewer → Auditor).
docs/adr, docs/rfcs, docs/prds	Humans + agents	The decision record: why each rule exists. Reference, not instruction.

The advice-vs-enforced axis

This is the distinction that matters most. A file can tell an agent something, or the system can make it true. Most files do one; a few do both.

• Advisory. AGENT_DEV_GUIDELINES.md, AGENT_DEV_PROCESS.md, the templates, the ADR/RFC/PRD record. These shape how an agent works but nothing fails the build if they are ignored. They rely on the agent reading and complying.
• Enforced. AGENT_POLICY.yaml is read by the gate before every write. Invariants with an enforcement block become failing CI tests. Protected paths are blocked at write time and at merge time. These do not depend on goodwill.
• Both. CLAUDE.md reads as instruction, but almost every hard rule is also wired to a checkpoint — a gate denial, a CI job, a CODEOWNERS block. The prose explains; the checkpoint enforces.

The core lesson

Steelmoth learned that an advisory file is not protection. The 2026-05-23 secret-cache incident broke three written rules that all existed as prose. Everything load-bearing was therefore moved onto the enforced side of this axis — which is what the rest of this site documents.

The two senses of “hard rule”

The phrase is used two ways, and it helps to keep them apart:

1. The literal, numbered HARD RULE 1–15 in CLAUDE.md — a specific, ordered list aimed at coding agents.
2. The general idea of a non-negotiable constraint. In that broader sense the architecture invariants are also “hard” — arguably harder, because several are enforced by automated tests rather than by an agent choosing to comply.

When someone says “that’s a hard rule,” it’s worth checking which sense they mean: a line in CLAUDE.md, or a property the system will not let you violate.

Canonical vs derived

One more trap: two files can describe the same rule, but only one is the source. The clearest case is PROTECTED_PATHS.md, which is generated from AGENT_POLICY.yaml. If they ever disagree, the YAML wins and a CI consistency check fails the build until they match again. Always edit the canonical file, never the derived copy.

See also

• Hard rules — the 15 rules in CLAUDE.md.
• Engineering standards — inside the standards folder.
• Agent policy (YAML) — the canonical source of truth.
• Architecture invariants — the enforced safety properties.