From dcaa3fb561c6b0c2e6a20e09a534e8932a360d75 Mon Sep 17 00:00:00 2001
From: Drew Stone <drewstone329@gmail.com>
Date: Wed, 27 May 2026 06:07:25 -0600
Subject: [PATCH] docs: add repo-layering section to AGENTS.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

agent-knowledge depends on @tangle-network/agent-eval (substrate) and on
@tangle-network/agent-runtime (runtime). The substrate MUST NOT import
from either — type inversions are a smell, not a feature.

Documents the rule, lists the substrate primitives agent-knowledge
consumes from agent-eval (AnalystFinding, RunRecord, optimizer types,
release-confidence types), and names the knowledge-domain types that
stay here (KbStore, KnowledgeFragment, KnowledgeChange, source adapters,
freshness store).

Pairs with the sibling layering sections in agent-eval/CLAUDE.md (PR
tangle-network/agent-eval#118) and agent-runtime/CLAUDE.md (PR
tangle-network/agent-runtime#67).
---
 AGENTS.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 0f076e4..e33ec89 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,6 +2,23 @@
 
 Use this package when an agent needs persistent, source-grounded knowledge that improves over time.
 
+## Repo layering — this package depends on agent-eval, never the reverse
+
+```
+agent-knowledge (this repo) ─┐
+                             ├──► agent-eval (substrate — the bottom)
+agent-runtime ───────────────┘
+```
+
+**Rule: agent-knowledge depends on agent-eval. agent-eval MUST NOT import from agent-knowledge.** No upward imports, no peerDependency declaration in agent-eval pointing at agent-knowledge. Substrate primitives that agent-knowledge needs (`AnalystFinding`, `RunRecord`, optimizer types, release-confidence types) live in agent-eval; this repo consumes them.
+
+Types that stay in THIS repo because they're knowledge-domain-shaped:
+- `KbStore`, `KnowledgeFragment`, `KnowledgeChange`
+- `KnowledgeDiscoveryDispatcher`, source adapters (`createCornellLiiSource`, `createIrsPublicationsSource`)
+- Freshness store + change-detection primitives
+
+**The test for "where does a type live?"** — does this concept make sense WITHOUT persistent knowledge or sourced fragments? If yes, it's substrate (agent-eval). If no, it's a knowledge-domain concept (stays here).
+
 ## Rules
 
 - Register sources before citing them: `agent-knowledge source-add <path>`.