Project-Template/CLAUDE.md

Read docs/DOC_TRUST_MAP.md before trusting anything else in docs/. It says which document owns which answer. This file is deliberately short and points at it rather than repeating it — a second copy of the map is the failure that map exists to prevent.

What this file is for

Only what an agent needs before it can read anything else, and that is not already owned by a document. If you are about to add current state, a task list, or a summary of docs/, it goes in the tracker or in docs/ respectively.

Exit codes are an API

Code	Means
0	did its work
1	refused for a normal, designed reason
2	did not run — a precondition failed. Never a pass
3	ran and the work failed
99	a lock was held; another copy is running

Three states, never two: ok / skipped / failed. An exit code alone cannot tell "nothing to do" from "I did nothing".

Before you finish

docs/WORK_CYCLE.md owns this and outranks anything here. In short:

• Run this project's own guards, not just its tests: <name them, e.g. python3 tests/run_all.py, bash scripts/doc-claims.sh>
• Never git add -A. Stage by explicit path — <bash scripts/commit-mine.sh if adopted>. A shared checkout means someone else's work is one careless add away from your commit.
• Update the documents this change triggered, in the same commit as the code. Check each document's Review trigger: line.
• Close issues with the evidence that proves them: a path, a symbol, a test name, or the command that shows it. "Done" is not a close.

Before you plan

docs/WORK_CYCLE.md lists six sections every plan must name: unified code, error handling, logging, blind spots, rolled-in landmine fixes, and hardcode-as-little-as-possible. Read them there.

Two standing instructions

Flag anything that looks wrong, even if it is not what you were asked about. Most real defects are found while looking at something else. Say so, then fix it or ask — a known bug that ships is a decision, and it is never yours to make silently.

Never print a credential. Not from a file, not from a command's output, not from a config subtree "with the secrets filtered out" — that filter has failed before, because it matched key names and the secret sat inside an object whose name was innocent. Name the variable or the path; never the value. To compare two secrets, compare hashes.

Conventions

• <Language/runtime and version>