Project memory

• Do not re-export ORES_* env vars in Bash tool calls.
• Always use compass to create new documents — never write .org files directly; use compass add to scaffold them.
• New captures go to the inbox bucket — triage to next/deferred separately.
• Always use compass to create agile artefacts — never write task/story files manually; always scaffold with compass add.
• Check recipes before searching for how to do something — doc/recipes/ is the first port of call for any project operation.
• Deploying skills runs Emacs only — run it directly — it is Emacs-only, not C++ compilation; run compass build --direct skills without asking the user.
• Deploy skills via compass build –direct skills, not manually — never write .claude/skills/<name>/SKILL.md directly; always run compass build --direct skills after editing a doc/llm/skills/<name>/SKILL.org source file.
• Builds can run outside the sandbox — use dangerouslyDisableSandbox: true for any cmake --build or make -C build/output/... call; compiler toolchain and vcpkg detection are blocked inside the sandbox.
• compass db commands run outside the sandbox — use dangerouslyDisableSandbox: true for compass db sql / db recreate; sandbox blocks localhost:5432.
• Set SSH_AUTH_SOCK for git operations — the sandbox has no SSH agent; export SSH_AUTH_SOCK before git push / fetch / pull.
• Git add and commit require sandbox disabled — git add / git commit fail with EROFS in this worktree; always use dangerouslyDisableSandbox: true.
• PR tables belong in task docs, not story docs — * PRs sections go in task .org files; story docs do not carry them.
• Check git commit conventions before committing — [component] title, Story-ID / Task-ID trailers, Co-Authored-By every time.
• Prefer compass over Unix tools for repo navigation — use compass search/list/show/where/story/task/capture before find / grep / ls; gaps in compass are captures, not workarounds.
• PR review runbook does not include merging — runbook ends at resolve threads; never call gh pr merge after review steps; user merges.
• Never cross worktree boundaries — all work stays in the active checkout; if a branch is taken by another worktree, flag it to the user rather than crossing environments.
• Plans live inline in tasks, not in doc/plans — design/analysis goes in the task's * Plan / * Notes and distils to the story's * Decisions; doc/plans/ is archive-only.
• Check runbooks before skills for multi-step procedures — for end-to-end procedures (PR review round, release, hotfix), check doc/llm/runbooks/ first; skills are building blocks, not workflows.
• Never type org-roam UUIDs from memory — copy from the target's :ID: drawer; generated UUIDs silently break the link graph.
• Cap C++ compilation builds at -j2 — never -j $(nproc); Emacs-only cmake targets need no cap.
• Fix codegen templates — never work around codegen gaps — fix the template; regenerate; never hand-write into generated files.
• Load .env before running test binaries — set -a && source .env && set +a before test runs.
• gh CLI requires dangerouslyDisableSandbox — keyring socket blocked by sandbox; always disable.
• Never amend commits — always create new ones — even when fixing the immediately prior commit.
• Do not push automatically after commits — stop after commit; only push when user explicitly asks.
• No forwarding headers when moving code between components — delete the original; update all consumers to the new path.
• PR bodies must use Markdown syntax — never org-mode in gh pr create/edit bodies.
• Use full UUIDs in PR Story/Task fields — always copy from :ID: drawer; never abbreviate.
• Only disable the sandbox when a command actually fails due to it — no preemptive bypasses.
• Do not override the subagent model — let subagents inherit the session model.
• Run validate_schemas.sh before pushing any SQL schema change — CI fails on missing drop scripts.
• Never open a PR unless the user explicitly asks — commit and push, then stop and wait.
• Avoid exclamation marks inside Bash heredocs — use Write/Edit tools for any content containing them; heredocs corrupt ! to \!.
• Comments describe how things are, never how they used to be — never contrast with a previous implementation; history belongs in commit messages and PR bodies.
• Include order is owned by clang-format — reject review suggestions to hand-tune C++ include order; the formatter is the single source of truth.
• Prefer compass commands for lifecycle operations — use compass pr sync/checks/create, task start/done, review list/reply/resolve — not raw git/gh.
• Rebuild a stale compass index before running compass commands — run compass index --org-roam-db-sync when staleness warnings appear; never proceed on a stale index.
• Scaffold tasks with content; let compass wire the tables — pass --goal and --acceptance to compass add task/story; never edit boilerplate afterwards.
• Task plans are historical records — never clear at close — distil decisions into the story's * Decisions but keep * Plan intact.
• Toolchain gaps are work items, never licenses for workarounds — implement through the toolchain or capture and ask; never hand-roll .org files or UUIDs.
• Don't use cat/–help after compass show/recipe — act on what it says directly; if something is missing, file a capture.

(none yet)

• Browser org-mode UI is ores.org-js; 'dashboard' is reserved — projects/ores.org-js/; ores-dashboard.el owns the "dashboard" name.

• Compass basic command syntax — search, list, show, where, story new, task new, add with required flags.
• Stuck vcpkg lock: sccache daemon holds it — sccache --stop-server frees it; pre-start the server to prevent; scan /proc/*/fd when lsof shows nothing.