diff --git a/assets/templates/AGENTS.md.template b/assets/templates/AGENTS.md.template index 22af6dc..ba2474e 100644 --- a/assets/templates/AGENTS.md.template +++ b/assets/templates/AGENTS.md.template @@ -92,6 +92,8 @@ Each primitive carries a **short name** for agent prose. When referencing a prim **Never a question.** The interrogative form — *"do you want me to create an entry / file this into the knowledge graph?"* — is forbidden. Capture is the default action, not an opt-in the user approves; the agent files first and reports after (user vetoes after via `git revert`, never gates before). Deferring capture to a user yes/no is the **permission-to-document anti-pattern** — knowledge that waits for permission is knowledge lost. Capture stays bounded by the Nous gate (proactive ≠ indiscriminate). +**Retrieval discipline (`/kg` for discovery, never substrate grep).** Knowledge-graph *discovery* — "what do we know about X", "load context for X", finding the relevant entities before reasoning — goes through **`/kg load `** (add `--terms ` for paraphrase/jargon topics); use `Read` only on a slug confirmed present in `docs/knowledge-index.md`. **Never** `find -name "$slug.md"` / `grep` / `cat` over `research/entities/` as a *discovery* mechanism: a guessed slug that doesn't exist returns nothing **silently** (a no-match is silent by default; often further masked by `2>/dev/null` / `if [ -n "$f" ]`), so the agent reasons over a *false-complete* context, and hand-picked slugs miss the relevant entities the catalog routing surfaces. This bans only *discovery* greps — `find`/`grep`/`cat` stay legitimate for operating on a **confirmed known file**, **tooling/skill internals** (the `/kg` loader's own body-grep, `bookkeeping` lint/index), and **bulk edits or counting** — just never as the step that decides what's relevant. + ### P7 — Freshness: Skill Freshness Check (Stale-Install Detector) **What**: Reports stale installed skills at SessionStart so they get refreshed before causing silent failures. diff --git a/references/primitives.md b/references/primitives.md index 8033ef2..d282437 100644 --- a/references/primitives.md +++ b/references/primitives.md @@ -123,6 +123,17 @@ Bookkeeping — and knowledge capture generally — is a reflex, not a request, Mental checklist before declaring graph-dependent work done: *Did this session produce material that belongs in the graph? Does my feature read graph state? Am I about to commit a snapshot?* — yes to any → file it / run bookkeeping, without asking. +### P6 Retrieval Discipline (`/kg` for discovery, never substrate grep) + +The reflexive trigger rule above is the *write* side of the knowledge graph; this is the *read* side. Knowledge-graph **discovery** — "what do we know about X", "load context for X", finding the relevant entities before reasoning — goes through **`/kg load `** (add `--terms ` for paraphrase/jargon topics; tier-2 body-grep also auto-fires on weak tier-1 hits). Use `Read` directly **only** on a slug confirmed present in the catalog (`docs/knowledge-index.md`). + +**Never `find -name "$slug.md"` / `grep` / `cat` over `research/entities/` as a *discovery* mechanism.** Two failure modes: + +1. **Silent miss** — a guessed slug that doesn't exist returns nothing (a no-match is silent by default; often further masked by `2>/dev/null` / `if [ -n "$f" ]`). The agent believes it loaded N entities when it loaded fewer and reasons over a *false-complete* context. `/kg` prints `Loaded N/total`, so a slug miss is visible (it does not, by itself, defend against the recall miss below — `--terms`/tier-2 do). +2. **Recall miss** — hand-picked slugs are bounded by agent memory; they miss the relevant entities the catalog routing surfaces (and `--terms` recovers the union). + +This bans only *discovery* greps. `find`/`grep`/`cat` over `research/entities/` stay legitimate for operating on a **confirmed known file**, for **tooling/skill internals** (the `/kg` loader's own tier-2 body-grep, `bookkeeping` lint/index/catalog generation), and for **bulk edits or counting/aggregation** — just never as the step that *decides which entities are relevant*. The user should never have to tell an agent to use `/kg` instead of grepping the substrate to find what's relevant. + --- ## P7 — Skill Freshness Check