Working in the Heimdall repo

Heimdall is the watchman: it gates other people's repos. So the bar here is the bar we sell. Read this before your first edit.

The rules that actually block you

• No stub, placeholder, TODO, or skeleton code. A PreToolUse hook scans every Claude Code write for unfinished code shapes (empty bodies, not-implemented throws, # TODO comments) and refuses the write — but that hook only fires inside a live Claude Code session. bin/heimdall-gate-run's pre-commit phase backs it up at the git layer: it re-scans the staged diff against the same shared shapes (bin/lib/heimdall-stub-patterns.sh), so the ban holds no matter which tool — or human — makes the commit. If you cannot implement something fully, say so — faking it is the one failure mode this repo exists to catch.
• Tests are bash. One file per surface: test/<name>.test.sh, run with bash test/<name>.test.sh. Exit 0 = green. A test prints PASS/FAIL lines and a count. Follow the shape of a neighbouring test rather than inventing a harness.
• Every assertion must be falsifiable. Before you call a test done, break the thing it covers and watch it go RED, then revert and watch it go GREEN. A test that cannot fail is not a gate — it is decoration.
• Test once, at the end. Run only the test file(s) you add or edit, once, after your changes are written; the full sweep (bash test/run-all.sh) runs once, on the final frozen tree, immediately before the landing commit — see CLAUDE.md "When the full gate runs". The break-it-and-watch-it-go-RED check above is a run on a different tree, not a repeat.
• Batch before you sweep. Merge every pending agent result first, then run ONE sweep; never merge anything between a green sweep and its push, and never start a second sweep while one runs — see CLAUDE.md "When the full gate runs".
• Quality gates run before push (heimdall-state check-quality-gates): tests green, lint clean, no untested changes. The gate is chosen per repo pushed: heimdall's own sweep repo gets that gate; a repo with .heimdall/repo-checks.json passes on a green, current receipt of its own checks (bin/heimdall-repo-checks run); any other repo gets a warning. Anything uncertain gets the strict gate — CLAUDE.md "Push gate".

Environment

• bash 3.2.57 on macOS. timeout(1) does not exist — use perl -e 'alarm N; exec @ARGV' -- <cmd>.
• Tests must be hermetic: redirect HOME, work in mktemp -d, never touch the real ~/.heimdall and never reach a live control plane.
• Nothing here is submitted to an external service during a test run. Local artifacts only.

Conventions

• Generated regions in tracked files live between HEIMDALL:<NAME>:BEGIN / HEIMDALL:<NAME>:END markers and are written by a renderer, never by hand — see bin/heimdall-render-version (README version region) and bin/heimdall-init (the AGENTS.md fence below). Match that pattern; do not invent a second one.
• Version truth is .claude-plugin/plugin.json .version. Every other surface is rendered from it.
• Independent work runs in parallel: batch independent tool calls into one message, and give each parallel agent its own file scope.
• One completed task = one atomic commit, conventional prefix.

CLAUDE.md carries the same conventions for Claude Code specifically. When the two disagree, they are both wrong — fix them together.

Heimdall — this repo is gated

Heimdall is a watchman wired into git. Gates run from pre-commit and pre-push, so every change here is checked whether or not an agent is in the loop.

• hmd verdict — the last gate result for this repo, and why.
• hmd demo — watch a gated build run end to end.

A deny blocks the commit. git exits nonzero and a BIFRÖST block prints on stderr naming what failed. Read the name, fix the code, commit again. HMD_SKIP=1 git commit … bypasses the gate but logs an unproven-merge receipt to .heimdall/receipts/unproven.log — visible, never silent.

Gates are external and falsifiable — satisfying the oracle is the only path. The verdict is computed from artifacts on disk, not from your explanation, so you cannot argue your way past a gate. Rewriting or weakening the test is not a path to green; it is the exact failure the gate exists to catch.

Same gate under Cursor CLI. This file is what Cursor's agent reads at session start too, and the pre-commit check above runs on its diffs exactly as it runs on Claude Code's — the one difference is a stub gets caught at commit here instead of at the write itself, since Cursor has no pre-write hook to catch it earlier.