knowledge-stack

Instruction file imported from YoussefChouj/Model_Reference_adaptive-controller_UAV_linux (.cursor/rules/knowledge-stack.mdc). Copyright stays with the author.

Knowledge Stack

Three-layer knowledge hierarchy (see session-lifecycle.mdc)

The wiki is the Ontology. It holds the formal shared conceptualization — what entities exist, what relationships matter, what invariants must hold. It is queried before planning, consulted before assuming, and updated only by explicit operator confirmation.

The knowledge-stack query order maps to these layers:

1. ccc search         → code layer (exact locations)
2. GRAPH_REPORT.md    → code layer (system-wide deps)
3. wiki/              → Ontology layer (why, design, principles)
4. docs/decisions.md  → Axioms layer (decision rationale)
5. docs/interfaces.md → Axioms layer (cross-subsystem contracts)
6. lessons.jsonl      → Axioms layer (past learnings)
7. Apify MCP          → External loop (no local answer)

When to use ccc vs grep

Adding knowledge: drop sources in raw/, then run the wiki ingest. Re-index the graph after wiki/code changes.

Gate enforcement (PreToolUse hook)

Claude Code's PreToolUse hook on Glob|Grep runs .agent_scripts/knowledge_gate.py.

• The gate classifies the command (snake_case / file:line → ccc; cross-subsystem / god node → graphify; why / ADR / architecture → wiki) and tells you which layer to consult.
• For each layer you consult, record it: python .agent_scripts/knowledge_gate.py --touch <layer>.
• After all three layers are touched, python .agent_scripts/knowledge_gate.py --unlock lets grep/glob through silently for the rest of the day.
• --unlock is hard to skip — it refuses until all three layers have been touched at least once. This forces the agent to know the full stack before raw-searching.
• Staleness-aware (via knowledge_state.py): if a layer is stale (HEAD moved past last_commit, or known files drifted), the gate's block message says so and tells you which refresh command to run (/graphify --update, /wiki ingest, etc.).
• Full protocol: wiki/concepts/knowledge-gate-enforcement.md.

Per-path refresh (Stop hook)

Claude Code's Stop hook runs knowledge_loop.py after every turn. The flow is:

1. The PostToolUse hook on Write|Edit|MultiEdit|NotebookEdit records each file the agent touches to a session-keyed JSONL trail: .agent_state/trail_<session>.jsonl.
2. At session stop, knowledge_loop.py run reads the trail, identifies the touched files, and runs the structural stages:
   • drift detect — re-evaluate stale flags in the manifest
   • annotate graph — mark touched graph nodes with last_touched_session + append a change_log entry
   • Recent change — append ## Recent change (YYYY-MM-DD) to affected wiki concept pages (idempotent — same date is skipped)
   • fresh stamp — mark graphify, wiki, and ccc fresh in knowledge_manifest.json
   • audit — log everything to .agent_state/knowledge_loop_log.json
3. The LLM stages are NOT in the hook path. Two options for them:
   • Mid-task: the working agent invokes knowledge_loop.py delta_update --paths a,b,c (or wiki_check --paths a,b,c). The script returns JSON prompts; the agent runs them through its own model and applies the result via path_refresh.merge_delta_into_graph(...) or path_refresh.autonomous_wiki_rewrite_from_verdict(...).
   • End-of-task: the working agent dispatches the dedicated uav-knowledge-writer subagent (.cursor/agents/uav-knowledge-writer.md, pinned to cursor-grok-4.5-high). That subagent has its own model + system prompt + read access to source files; it does the LLM call, parses the result, applies the rewrites (with backup), and appends to the audit log.
4. The whole-corpus /graphify is not triggered automatically — only the structural annotation. The next user-initiated /graphify --update is when the LLM re-extraction runs.
5. The git post-commit hook fires the same structural loop in the background on every commit (installed via python .agent_scripts/install_post_commit.py install).

This means the knowledge graph becomes a journal of the agent's path, growing richer with each task, with no human in the loop and no external LLM API key required.