yggdrasil: Instructions file for Claude Code

AGENTS.md — working on the kit itself

You are in the kit's own repository, not in a project that uses it.

• Installing or operating the kit inside a project → read PLAYBOOK.md (Portuguese).
• Evaluating what this is → README.md.
• Changing the kit's code → this file.

What ships where

scripts/ is the source of truth. setup.py copies relabel.py, hook-update.py, hook-update-knowledge.py, wrap.py, hook-prewrap.py, _gitparse.py and check.sh into a target project's graphify-out/. Editing an installed copy inside some project fixes nothing here — change scripts/.

If you add a runtime script, it must be added to the copy list in setup.py, and — if hook-prewrap.py depends on it — to the fail-open existence check in emit_allow_wrap. Missing either turns the wrapper off silently.

Invariants — do not "clean these up"

These are listed here as change constraints, not as behavior documentation: the behavior is defined by the code and by PLAYBOOK.md. If an entry below ever contradicts them, the code wins and this list is what needs fixing. Each item cost a real incident to learn.

• Never Path.cwd() to locate graphify-out/. Use resolve_root(__file__) from _gitparse.py. Agents run commands with the cwd inside a subrepo; cwd-based resolution fragmented stats.jsonl (one dataset, N partial copies) and silently disabled the wrapper. The ascending search is capped at $HOME on purpose.
• Hook paths in settings.json are absolute. A relative path dies at load with the cwd in a subrepo and, being PreToolUse[Bash], blocks every Bash command — including the GRAPHIFY_WRAP=0 bypass, which the hook never lives to read.
• Fail-open, absolutely. Any exception in wrap.py or hook-prewrap.py runs the raw command with output untouched. Lossy compression without an escape hatch is worse than no compression.
• Exit codes are never rewritten. Not in wrap.py, not in check.sh. A check that cannot verify exits 2, never 0 — a false green is worse than a false red.
• Failures are never summarized. Build-fix needs the real error verbatim.
• Compound commands are never wrapped (|, ;, &, backtick, $(). Wrapping half a pipe measures post-pipe bytes and distorts the stats that gate features.
• layer_vocab ships empty. Layers are what a given project practices, never a kit constant. Seeding a default vocabulary is a rejected proposal, not a TODO.
• miss_lex does not exist in stats.jsonl and is not a gate. If a stale comment says it's coming, the comment is wrong.
• _gitparse.py keeps its name despite now holding resolve_root too — installed copies import that name and the hook checks for that filename before rewriting.