Hard rules

The sixteen non-negotiable rules in CLAUDE.md — each one written because skipping it once cost real time.

CLAUDE.md is loaded into every Claude Code session. Its opening line: “These rules exist because skipping them has cost real time. Treat as non-negotiable.” Each rule is a scar. What makes them more than good intentions is that almost every one is backed by a real checkpoint — the gate, a CI job, a CODEOWNERS block, or an invariant fitness test.

A numbering quirk worth knowing

The list is not a clean 1–16. There is a RULE 5-bis (standards before any work) and a RULE 7-bis — and 7-bis is printed before rule 7. The “-bis” rules were inserted next to the rule they’re closest in spirit to, rather than renumbering everything. It looks like a typo; it isn’t.

The sixteen (plus two)

Rule	In plain words	How it’s enforced
1	Deploy the dashboard only through scripts/compose-dashboard-deploy.sh — never a bare docker compose build.	Two containers serve the dashboard; the script keeps them in sync. CI + the deploy script’s CSS-fingerprint check.
2	Dashboard work isn’t done until the user’s real browser shows it.	Procedure: compare CSS fingerprints on :3011 / :3012, then confirm visually. “Tests pass” is not verification.
3	Pre-flight before any rebuild — list what’s running first.	Procedure (pre-flight commands) before touching a live surface.
4	Database migrations land before the code that needs them.	Single Postgres stm-data-postgres; migrations recorded in core.schema_migrations; CODEOWNERS guards the migrations path.
5	Memory is mandatory reading — scan it before non-trivial action.	Auto-loaded each session; relies on the agent reading it.
5-bis	Load the engineering standards before planning, editing, or reviewing — even for a plan.	Tied to INV-021; the standards name the process.
6	No container build/recreate/start without an explicit yes in the current thread.	The gate treats build/recreate shell commands as approval-required.
7-bis	Never remove or hide anything from the dashboard’s visible surface.	A sidebar-no-removal CI check + CODEOWNERS on the sidebar file.
7	Never hand the user commands to run — do the work yourself.	Behavioural rule; the agent runs on the same host and acts directly.
8	Every shipped change updates CHANGELOG.md in the same change.	A changelog-updated CI job; scripts/check-release-versions.sh.
9	Canonical repo is /home/mareekkk/steelmoth; active coding happens in WIP worktrees.	Worktree discipline; one branch per worktree, one agent per worktree.
10	Never build a secret broker inside the compose stack — the broker lives only on prontera.	INV-024 fitness tests (four scanners) + the gate. See the policy.
11	The Operator Authority gate is the single source of truth — no parallel scope-checks, no ignoring an exit code of 2.	This is the gate. AGENT_POLICY.yaml is canonical.
12	One brain; channels (Telegram, Slack, …) are thin transports, never their own runtime. New workers need approval at every gate.	INV-025 fitness test + the canonical-containers CI check.
13	A message ending in “?” gets an answer, not an action.	Behavioural rule; read-only is allowed, mutation is not.
14	After a force-push dismisses a PR approval, re-request review before asking the operator to re-approve.	Procedure via scripts/gh-as-soho.sh; ties to CODEOWNERS approval.
15	No AI attribution in the operator’s work product — overrides the harness default footer/trailer.	INV-026, the bind-all anchor for every agent.
16	Discover before you build — search the codebase for an existing implementation and reuse/extend it before writing new code; if nothing equivalent exists, stop and tell the operator first.	INV-027 + the Architect-pass discovery gate. Process rule — memory-only, no mechanical backstop.

Why “exit code 2” appears in rule 11

Rule 11 says never to ignore a gate exit code of 2 and retry under a different command shape. That number is load-bearing: the gate returns 0 for allow and 2 for deny, because the hook contract treats exit 1 as a non-blocking error — the tool would run anyway. The full story is on the gate’s page.

The pattern across all sixteen

Read the enforcement column top to bottom and the architecture reveals itself. The rules that can be a human mistake — deploys, builds, schema order, secret brokers, hidden UI, AI attribution — are pushed onto a machine checkpoint. The rules that are about judgement — answer the question, don’t hand over commands, read memory — stay behavioural, because no gate can encode them. The hard rules are the human-readable face; the policy, the gate, and the invariants are the enforcement behind them.

See also

• The gate — where rules 6, 10, and 11 actually bite.
• Architecture invariants — INV-024/025/026 behind rules 10/12/15.
• CODEOWNERS — the merge-time backing for rules 4, 7-bis, and 14.
• Governance files — the two senses of “hard rule”.