codingest CLAUDE.md

codingest — project instructions

Standalone extraction of KGLite's code_tree component: parse polyglot codebases into queryable kglite knowledge graphs. The graph engine and MCP server are imported from KGLite as cargo libraries; this repo owns only the code-tree component. See README.md for the workspace map and PARITY.md / BENCHMARKS.md for the regression record.

Authority: CLAUDE.md is the authority this repo's conventions are regenerated from, with AGENTS.md as its generated adapter; for the skills the authority is tracked .agents/skills/, and .claude/skills/ is a generated adapter of it. Edit the authority and regenerate in the same action — never edit an adapter. (This line is exempt from the CLAUDE.md↔AGENTS.md substitution — it names the authority literally in every copy, per doctrine R7/R14.)

Working style

• Evidence over assertion. For a bug, reproduce it and confirm the root cause with evidence before fixing. For a behaviour-preserving refactor, probe the actual graph output first — don't trust your mental model.
• No bugs left behind. A defect you notice mid-task gets fixed (in scope) or filed via add-todo (out of scope) — never silently stepped over. The builder now lives only here, so builder bugs are ours to fix; if it traces to the shared kglite engine (kglite::api, Cypher, storage), route it to KGLite via notify (KGLite is read-only here).
• Offload, don't print. Write long output (stats JSON, bench tables, graph dumps, big diffs) to dev-docs/temp/ (>1-day purge) or dev-docs/bench/out/ and report the path. Keep responses under ~400 tokens.
• Tooling discipline. Don't read a gate's status through a tail/head pipe that can hide a failure — confirm the command actually reported success. After any builder/parser change, run cargo test (not just a hand-picked subset), and always the parity test if transformed code_tree source moved. Three more shapes of the same trap, each of which failed in the reassuring direction (doctrine R2):
  • git add with one bad pathspec stages NOTHING. It is all-or-nothing: one typo'd or since-renamed path aborts the whole invocation, so the other files are not staged either — and the following git commit still succeeds, on a commit missing the change. Read back git diff --cached --name-only.
  • grep -c exits 1 when the count is zero, so grep -c … && next breaks the chain on exactly the empty result you needed to act on, and under set -e it kills the script. Capture it (n=$(… | grep -c … || true)) and test the number.
  • A backgrounded command's output must be read from its artifact. An echoed exit status, a "done" line, or the absence of visible errors is not the result — open the log the run wrote. This is how a failed background build reports green.
  • Recipes never invoke bare python and never verify via >/dev/null 2>&1; echo $?. A shell alias makes bare python report the alias's failure as the checker's verdict, and the null-masked $? hides which command failed — use the venv interpreter and read the target command's own status.
• Testing cadence: targeted per landing, the full battery once at the end. A landing's gate is the suites chosen to catch what that change could break — its touched surface plus that surface's direct consumers. This does not weaken "run cargo test, not just a hand-picked subset": the Rust battery is cheap and stays the per-phase gate. It applies to the heavy make gate steps (release-gate scripts, bench smoke, wheel + tests/python) — those run once before a branch's first push and once over the union at the program's end, never per phase. Per-phase heavy runs buy nothing a completion-time run does not, and their cost is what makes agents quietly stop running them.