{"slug": "kg-concepts-before-code-checklists-after", "title": "KG Concepts Before Code, Checklists After", "summary": "A how-to published on the Terraphim site demonstrates running `terraphim-agent code` inside a knowledge-graph policy loop that rewrites `npm install` to `bun add` before a tool call executes. The `pre-tool-use` hook with the opt-in `--rewrite` flag converted the command `npm install react` into `bun install react`, and the `validate --checklist code_review` step scored a sample output 0/5, flagging missing tests, documentation, error_handling, security and performance. The article argues the checklist guards the write and judges the result so the model is never trusted to police itself.", "body_md": "The [Graph Embeddings for Checklists](https://terraphim.ai/posts/graph-embeddings-checklists/) article\nshows how a knowledge graph acts as an enumerable checklist around an LLM call:\n`terraphim-grep` before it, `terraphim-agent hook` and learning after it. This\nhow-to applies the same loop to `terraphim-agent code` — the bounded coding loop —\non the simplest possible concept: **`npm install` must become `bun add`**.\n\nEvery command below was run while writing this article; the outputs are real.\n\n## TL;DR\n\nDeclare the concept once (`kg/*.md` or `.terraphim/rewrite/*.md` with\n`synonyms::`), let the hook find `npm install` in a proposed tool call and\nprescribe `bun add`, run `code` inside the policy gate, then validate the\nproduced work with `validate --checklist`. The checklist guards the write and\njudges the result — the model is never trusted to police itself.\n\n## Declare the Concept\n\nOne file, written once, compiled into the role's automaton. From this site's own\n`.terraphim/rewrite/bun install.md`:\n\n```\n# bun add\n\nInstall dependencies using Bun package manager.\n\nsynonyms:: npm install, yarn install, pnpm install, npm i, yarn add, pnpm add\n```\n\n## Before `code`: The Hook Checks the Action\n\nAn agent proposing `npm install` hits the checklist first — `pre-tool-use` with\n`--rewrite` (opt-in so a stray substring can't silently mutate a destructive\ncommand):\n\n```\necho '{\"tool_name\":\"Bash\",\"tool_input\":{\"command\":\"npm install react\"}}' \\\n  | terraphim-agent hook --hook-type pre-tool-use --rewrite \\\n      --role \"Terraphim Engineer\" --json\n{\n    \"tool_input\": {\n        \"command\": \"bun install react\"\n    },\n    \"tool_name\": \"Bash\"\n}\n```\n\nThe concept fired: `npm install` in, `bun install` out — a checklist line\nexecuted *before* the tool call runs, with a named edge (`bun install.md`) to\naudit.\n\n## Inside `code`: The Loop Is Gated\n\n`code run` puts the model inside a bounded loop — every tool call is\npolicy-decided, audited to JSONL, and the run is exit-coded for callers:\n\n```\nTERRAPHIM_CODE_MODEL=auto \\\n  terraphim-agent code run \"Create a Cargo.toml and src/main.rs that prints Hello from terraphim\"\n- **Cargo.toml** — package `terraphim` v0.1.0, edition 2021, no dependencies\n- **src/main.rs** — `fn main()` printing `Hello from terraphim`\n\nVerified with `cargo run`, which compiled cleanly and output:\n\n    Hello from terraphim\n```\n\nThe hook and the gate compose: the KG checklist shapes what commands the agent\nmay propose, the deny-first policy decides whether a call runs at all, and the\naudit JSONL records both decisions. Sessions persist as transcripts plus\n`TurnStep` checkpoints, so `code resume` replays context and reads persisted\nsteps back.\n\n## After `code`: The Checklist Judges the Result\n\nThe same graph that prescribed `bun` judges the output — `code_review` is a KG\nchecklist, not a prompt suggestion:\n\n```\necho \"no tests, unwrap() everywhere\" \\\n  | terraphim-agent validate --checklist code_review\nChecklist 'code_review' Validation for role 'AI Dark Factory Author':\n  Passed: false\n  Score: 0/5\n  Missing items:\n    ✗ tests\n    ✗ documentation\n    ✗ error_handling\n    ✗ security\n    ✗ performance\n```\n\nZero-inflated honesty applies here too: if the produced work mentions none of\nthe checklist items, the report says so with the missing set enumerated — the\nsame \"honest empty case\" property `terraphim-grep` shows on retrieval.\n\n## The Loop\n\n```\ndeclare kg/*.md ──► hook pre-tool-use (npm install → bun add)\n                              │\n                    code run — gated, audited, resumable\n                              │\n            validate --checklist code_review — the verdict\n                              │\n              learn/correct — feed misses back into synonyms\n```\n\n## Honest Notes\n\n- `hook --rewrite` is opt-in (`--rewrite` flag, default off): findings are\nalways emitted; the*substitution* is explicit. Without`--rewrite` the same\nrun returns the input unchanged with the finding attached.\n- `terraphim-agent replace` in this build reports`changed: true` while\nreturning the input unchanged — the findings-based`hook` path above is the\ncontract to rely on (this caveat is carried from the checklists post, which\ndocumented it first).\n- `auto` on`terraphim-llm-proxy` resolves through the measured dynamic pool\nwith a static`MiniMax-M3` fall-through, so a gated-out pool degrades to a\nhealthy lane rather than failing — fixed during this session (the pool's\neligibility gates had evicted every candidate while the static fallback was\nabsent;`auto` answered with a generic 400). A dead member in the pool\n(`kimi-for-coding-highspeed` , subscription 403) still costs probe traffic.\n- Roles resolve from the device-settings config; tests and CI can inject a\nthesaurus directly via `TERRAPHIM_CODE_AUTOMATA_PATH` rather than registering\na role.\n\n## The Demo\n\nTwo `fframes` renders of real captures back this article — every terminal\nline is a real command output captured while writing it.\n\nThe joined storyline (`spec → graph → gate → surface → code → checklist`): a\nreal `spec.md`, `terraphim-grep` firing `validation gate` on the context, the\ngate denying two shell calls by rule name, the tools/commands/policy surface,\na verified `cargo run` output, and the `0/5` checklist verdict on\nspec-violating code.\n\nThe disciplined-engineering cut (`issue → research → design → impl → verify → validate`): real issue [#431](https://git.terraphim.cloud/terraphim/terraphim-clients/issues/431)\nthrough the `disciplined-*` phases — the `rg` finding, the design decision,\nreal commits, `fmt`/` blaze` verification, and the checklist verdict.", "url": "https://wpnews.pro/news/kg-concepts-before-code-checklists-after", "canonical_source": "https://terraphim.ai/posts/kg-concepts-code-checklists/", "published_at": "2026-10-28 00:00:00+00:00", "updated_at": "2026-10-28 21:43:08.672359+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "ai-safety"], "entities": ["Terraphim", "terraphim-agent", "terraphim-grep", "Bun", "npm", "Cargo"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/kg-concepts-before-code-checklists-after", "markdown": "https://wpnews.pro/news/kg-concepts-before-code-checklists-after.md", "text": "https://wpnews.pro/news/kg-concepts-before-code-checklists-after.txt", "jsonld": "https://wpnews.pro/news/kg-concepts-before-code-checklists-after.jsonld"}}