Rules and protections

The idea in one paragraph

A rule is a Markdown file in .claude/rules/ that tells Claude how to behave. Claude reads it and follows it, but a rule is only words: if Claude misreads it, nothing stops the action. A wall is code that runs before or after an action and refuses it whatever Claude decided. HEADING OS uses both. Rules carry judgement ("ask before an irreversible step"). Walls carry the things that must never happen by mistake ("no API key in a tracked file", "no push you did not ask for"). When a wall refuses, the action did not happen, and the message says why and what to do instead.

A few words used below:

• Engine: the .heading-os folder. Code only, never your data.
• Data repository: the .heading-os-data folder next to it. Everything you create lives there.
• Registry name: a logical name for a place in the data repository. .venv/bin/python scripts/data-path.py path <name> prints where it is today.
• HELM and yard: your main engine copy, and a separate git worktree for one task. YARDS.md explains both.

Always-on rules

These files load into every session. You do not call them. You notice them in how Claude answers.

Prompt refinement and the approval stop

File: .claude/rules/prompt-refinement.md.

What it asks of Claude. When a request is ambiguous, multi-step, irreversible, or changes the shape of a task, Claude does not start at once. It restates the request as a full instruction, opening with "It looks like you want me to do the following:", and lists the objective, scope, deliverables, constraints, assumptions and open questions. The last part is a short Measure: block (see "Measurable execution" below). Then it stops and waits.

A direct, plain request or a question is done at once, with no stop.

What you notice. For bigger tasks, a structured restatement and a pause. Approve with "approved", "proceed", "go", "execute" or "yes". Before the first action, Claude saves the approved instruction with scripts/prompt-archive.py save and tells you the file's path. From then on, that file is the instruction. If the file and the chat disagree, the file wins.

How to work with it.

• Start a message with ! to skip the stop (for example !fix the typo in the heading). Claude still saves the task's instruction file if the message defines a new task.
• A direct answer to a question Claude asked, or a one-step correction such as a rename, also skips the stop.
• .venv/bin/python scripts/prompt-archive.py list shows this session's saved instructions in order. latest prints the newest one's path.

Measurable execution

File: .claude/rules/measurable-execution.md.

Every expanded task from the rule above ends with a Measure: block. It always names the check that defines "done", for example a test exit code, a count, or a file that exists and passes its audit. When the task has a clear end condition, Claude may also propose a ready-to-paste /goal <condition>. When the task repeats or needs polling, it may propose /loop <interval> <prompt>. These are proposals only. Claude never starts /loop or /goal by itself. You can accept, change or replace the metric at the approval stop.

Human-gated sending

File: .claude/rules/lethal-trifecta.md.

The risk. An assistant that holds private data, reads untrusted content (mail, web pages), and can send messages out can be tricked by that content into sending your data away. HEADING OS keeps the third part, sending, behind a human.

What it asks of Claude. Every outbound message is a draft. A skill or a background job prepares it and stops. Nothing sends by itself.

What you notice.

• Drafts, never sends. In the Action Queue, a card that can send is in the gated tier. It sends only when you type .venv/bin/python scripts/action-queue.py approve <id>, and it sends in that same command. list, show, edit and dismiss let you review and change cards first.
• A new kind of action that can send is gated by default. An action type the risk ledger (config/tool-risk.json) does not know resolves to gated.
• A wall backs this up for Claude's own commands. The release gate (see "Session walls") refuses a command that sends through the Mattermost, Telegram or Gmail clients, or through scripts/send-email.py, unless your most recent message asks for it with a clear instruction such as "send it". A question like "did you send it?" does not count.

The one exception the rule names: notifications to yourself. A message that can only reach you, such as a timer's alert to your own Telegram chat, sends without a click. scripts/utils/telegram_notify.py accepts only the targets set in your environment (HEADING_OS_SELF_TELEGRAM_TARGET, or the per-feature *_TELEGRAM_TARGET variables) and refuses any other recipient. If none is set, it sends nothing.

A known gap: Sentinel answers meeting invites by itself. The rule says there is one exception. In the shipped code there is a second one that the rule does not name. Sentinel (/sentinel, scripts/sentinel.py) can accept or decline calendar invites on its own, with no approval per invite, and a decline can carry a reply message to the person who invited you. Two settings in its config turn this on, and both ship turned on:

calendar:
  auto_accept: true
  auto_decline: true
  decline_message: ""

When a key is missing, the code also treats it as true. Sentinel reads its config from sentinel_config.yaml in your data repository's config folder (registry name data-config; .venv/bin/python scripts/data-path.py path data-config prints it). If that file does not exist, it reads the shipped example, scripts/sentinel_config.example.yaml in the engine, which has both switches on.

To turn this off:

1. Copy scripts/sentinel_config.example.yaml from the engine to sentinel_config.yaml in the data-config folder of your data repository, if you do not have that file yet. Do not edit the engine copy.
2. In your copy, set auto_accept: false and auto_decline: false under calendar:.
3. Restart Sentinel in HELM so it reads the new file. It reads the config once, when it starts.

Humanisation and the confirmation line

File: .claude/rules/humanization.md.

What it asks of Claude. Prose should read as written by a person: concrete names, dates and numbers in every paragraph, a clear position instead of hedging, and none of the usual machine phrases. For outbound text (emails, posts, proposals) Claude writes a content draft first and then does a separate voice pass. Before it rewrites existing text, it tests that text with scripts/humanization-check.py. If the text already scores as human, Claude leaves it exactly as it is, byte for byte.

What you notice. Every prose deliverable ends with a confirmation line built from two tools: the word count and hidden-character verdict from scripts/sanitize-text.py --scan, and the result of scripts/humanization-check.py. If you give Claude your own draft, it asks before changing your voice.

Hidden characters

File: .claude/rules/hidden-chars.md.

Generated text must contain only visible characters, ordinary spaces and newlines. Zero-width spaces, soft hyphens, non-breaking spaces, direction marks, byte-order marks and other invisible Unicode count as defects. The rule owns the confirmation line: Word count: X. Hidden characters: <what the scan reported>. Both values come from scripts/sanitize-text.py --scan, never from a guess. A wall backs this up: the post-write sanitize hook (see "Session walls") scans every file Claude writes.

Voice

File: .claude/rules/voice.md.

Claude states only what it knows and says when it is unsure. It asks clarifying questions in one block when a gap would change the result, and goes ahead when the task is plain. It answers in the language of your message. Internal dates use YYYY-MM-DD, and times use the timezone in HEADING_OS_TZ (UTC when unset). In prose it writes, it uses no em-dash and no -- as punctuation. Text it only edits, and quotations, keep their original punctuation.

One part of this rule is about structure: Claude must not create, change or delete workspace infrastructure (rules, skills, scripts, config, reference files, templates) without your approval. It proposes the change and waits. Output files that skills produce are exempt.

Negotiation style (Voss)

File: .claude/rules/voss.md.

Any message Claude drafts for you follows a few habits from Chris Voss's negotiation method: acknowledge the other person's likely concern before making your point, ask "how" and "what" questions instead of giving demands, use precise numbers rather than round ones, and do not split the difference. /voss and /meeting-prep build a full plan for one conversation.

Terminology

File: .claude/rules/terminology.md.

This file ships empty. It holds placeholders for your company name, your product names, your word for your team, any special vocabulary, and your stated principles. Until you fill it in, Claude writes in plain neutral English. Fill it in once, early, because skills that draft text read it.

Memory discipline

File: .claude/rules/memory-discipline.md.

What it asks of Claude. A remembered snippet, an index entry or a summary is a pointer, not a fact. Before any consequential action (a commitment, a decision, a number, a deadline, a person's position, the state of a deal or task), Claude opens the real record and works from it. If the pointer and the record disagree, it says so.

If you run Hindsight (HINDSIGHT.md), Claude asks Hindsight first for anything in your records, and shows what Hindsight returned. Two walls back this up: "Ask Hindsight first" and the Hindsight-shown check, both below. Without Hindsight, neither wall does anything.

A memory to keep is a file in the data repository's auto-memory folder. Claude never deletes those files unless you tell it to.

Persistence

File: .claude/rules/persistence.md.

HEADING OS keeps data in files and SQLite, and runs no database server. Any file format is fine. In-process stores such as SQLite are fine. A design that needs Postgres, MySQL, Redis, Elasticsearch or a similar server is refused, and Claude proposes the file or SQLite form instead. When Claude proposes something that stores data, it says where, and confirms that nothing new listens on a network port.

Console-first

File: .claude/rules/console-first.md.

Everything must work from the terminal, a command line and Claude Code chat. A web page can be added for convenience, but nothing may depend on one. When Claude builds a capability, it builds the command-line path first and confirms it.

Skill router

File: .claude/rules/skill-router.md.

Claude matches your plain-language request to a skill and announces it, for example "Using /osint for this". If two or three skills fit, it shows a short numbered menu and waits. Typing a /command yourself skips the matching. Skills marked manual in the router's table never start from a sentence; you type them. The table is generated from each skill's own metadata by scripts/generate-skill-router.py, and a commit gate refuses a table that drifted from the skills.

Before any skill that reaches websites which block data-centre addresses (/yt-pulse, /osint, /playwright on YouTube, anything that calls scripts/firecrawl.py), Claude asks a VPN question from reference/vpn-preflight.md and waits for your answer.

Lific

File: .claude/rules/lific.md. Applies only if you use Lific (LIFIC.md).

• Claude never runs lific connect in any form. It rewrites your whole ~/.claude.json.
• When you say "don't forget to do X" in passing, Claude searches for a matching issue first, then creates one at backlog. It never creates an issue at todo; deciding that a task is real is yours.
• A yard may only add comments and create issues. Status changes, links and deletions happen in HELM.
• An issue becomes done through the merge commit's closes <ID> line, fed to lific git-hook.
• Nothing secret goes into an issue or a comment. A deleted issue keeps its text for thirty days, and the audit trail survives deletion.

Security

File: .claude/rules/security.md.

No password, key, token or session data goes into any file git tracks, in the engine or in the data repository. Keys belong in the gitignored .env, account passwords in a password manager, OAuth tokens and sessions in the gitignored .sessions/ folder. Two commit-time protections can be switched off by hand, and the rule forbids both: git commit --no-verify (or -n), and setting core.hooksPath. If a secret is ever committed, rotate it first, then remove it from history, then record the incident under the registry name security-incidents.

Path-scoped rules

These rules load only when Claude works on a file that matches their paths: list. A rule with a data-scope: list covers files in the data repository; Claude Code does not match those itself, so the data-path redirect hook names the rule to Claude the first time in a session that it touches such a file.

The walls

Session walls (Claude Code hooks)

Hooks are registered in two files. .claude/settings.json is tracked and registers two. scripts/setup-platform.sh writes the rest into the gitignored .claude/settings.local.json from a template for your platform. If you skip setup-platform.sh, most walls are not armed and nothing tells you.

The PreToolUse dispatcher. .claude/hooks/_dispatch.py runs before every Write, Edit, MultiEdit, NotebookEdit, Bash, Read, Grep and Glob call, and before agent dispatches and codegraph and Hindsight tool calls. It runs its checks in order, and the first refusal wins. A refusal appears in Claude Code as a denied tool call with the reason below. Every refusal is counted, without its content, in a denial log; .venv/bin/python scripts/denials.py reports the counts, --detail lists each refused path, --days N limits the period.

Some checks only give advice and never block:

• A notice at 200 file writes in a day, and when the same file is written six times within one session's last twenty writes.
• A notice at 75 tool calls in 30 minutes for one session, and when one tool runs four times in a row with the same arguments.
• A delegation note after a session has read more than 12 different files by hand since it last dispatched an agent. To record why the work is serial, run .venv/bin/python scripts/fanout-note.py "<reason>".

Other session hooks.

Permission denials. The settings template also tells Claude Code to refuse some commands outright, with no hook involved: git push --force, git push -f, git push --force-with-lease, git commit --no-verify, git commit -n, rm -rf /, and reading .env, .sessions/, *.pem, *.key and .credentials.json.

Commit gates

pre-commit install arms these in each clone. They run on git commit and look at the staged files. A refusal stops the commit, and the output names the gate and the file. Never bypass them with --no-verify.

To run every commit gate over what you staged, before you commit: pre-commit run --files $(git diff --cached --name-only).

Push gates

The pre-push hook. .venv/bin/python scripts/install-git-hooks.py installs .githooks/pre-push into the engine and .githooks/pre-push-data into the data repository. On every git push, the engine hook first runs the push-time content scan of scripts/push-all.py (secrets, routing, real-entity content), then the tests this push can reach through scripts/run-tests.py --pre-push. Any refusal stops the push. The test step can take minutes; that is normal, not a hang.

scripts/push-all.py commits and pushes both repositories, the data repository first. It runs only in HELM; in a yard it stops with this script runs from HELM (the main clone) only, not from a YARD worktree. Before it commits, it scans everything about to leave. Its refusals start REFUSING TO PUSH, for example:

• a secret in the content about to be pushed;
• a file that looks like a credential by name (.env, .session, cookies.json, .sessions/);
• the rebuildable .memory-index/ folder being tracked;
• data-class files or real-entity content in the engine;
• a ratchet finding (the same checks as check-push-ratchets.py).

It pushes only to an allowed remote, only from main, and only when the engine's pre-push gate is armed. After the push, it checks that the branch is level with the remote and does not trust the exit code alone.

Options: -m "<message>", --no-commit (push existing commits only), --dry-run.

scripts/check-push-ratchets.py runs the same engine ratchets as push-all.py, on the current checkout, and writes nothing. It works in a yard. Run it before you say a branch is ready, and in HELM on the merged tree before the merge commit. Exit 0 means nothing refused; exit 1 means at least one ratchet refused, and the push would be refused too. --verbose prints every scanner's report.

How these fit SECURITY.md. SECURITY.md names seven layers that keep private data out of the engine. In this guide they appear as: the static bypass guard and the runtime tree-clean check (the data-root-bypass-guard commit gate), the leak guard (leak-guard-paths and leak-guard-staged), the data-path redirect hook, the push-time wall (push-all.py and the pre-push hook), and the content guard (content-guard-workspace, and again at push). SECURITY.md also names a build partition; this guide does not describe it.

Switches you control

Only the switches below exist in the code. Most walls have none on purpose.

There is no switch for the release gate, the yard guards, the crashed-wall block, or the push-time secret scan.

Check that they are armed

Run these from the engine folder after install and after every update. Each exits non-zero when something is missing.

1. Session hooks: bash scripts/setup-platform.sh --check. It names each missing hook registration.
2. Commit gate: uv run python scripts/install-hooks.py --check. It reads the hook file git would run and follows core.hooksPath if set.
3. Git hooks: uv run python scripts/install-git-hooks.py --check. It checks the pre-push gate and the pre-commit hook in the engine and in the data repository.
4. Push ratchets: .venv/bin/python scripts/check-push-ratchets.py.

These checks confirm that a hook is registered or installed. They do not prove that it ran. To see that the walls do refuse things, look at the denial counts: .venv/bin/python scripts/denials.py --days 7.

Common problems