From a4f71d9187ac1589204c8f97d8bc40cbe1dd68f8 Mon Sep 17 00:00:00 2001 From: "Carlos D. Escobar-Valbuena" Date: Mon, 8 Jun 2026 11:18:58 -0500 Subject: [PATCH 1/2] =?UTF-8?q?feat(P6):=20retrieval-discipline=20reflex?= =?UTF-8?q?=20=E2=80=94=20/kg=20for=20discovery,=20never=20substrate=20gre?= =?UTF-8?q?p?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Track A of BRO-1426. Agents reflexively find/grep/cat over research/entities/ instead of /kg, bypassing the routing layer. Two observed failure modes: silent miss (a guessed slug that doesn't exist returns nothing, swallowed by 2>/dev/null — agent reasons over a false-complete context) and recall miss (hand-picked slugs miss the relevant entities catalog routing surfaces). Add a P6 retrieval-discipline sub-rule (read companion to the existing substrate-edit write rule) to the canonical spec (references/primitives.md §P6) and the install template (assets/templates/AGENTS.md.template §P6), so bstack bootstrap/repair propagate it to every workspace. Reasoning-enforced reflex — no hook/gate — consistent with the P6/P9 reflexive-trigger pattern. No primitive-count change (sub-rule, not a new primitive). Evidence: research/entities/pattern/substrate-grep-bypasses-routing.md + the BRO-1425 benchmark. Workspace AGENTS.md §P6 updated in lockstep. BRO-1426 Co-Authored-By: Claude Opus 4.8 (1M context) --- assets/templates/AGENTS.md.template | 2 ++ references/primitives.md | 11 +++++++++++ 2 files changed, 13 insertions(+) diff --git a/assets/templates/AGENTS.md.template b/assets/templates/AGENTS.md.template index 22af6dc..8988057 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** (typically masked by `2>/dev/null`), so the agent reasons over a *false-complete* context, and hand-picked slugs miss the relevant entities the catalog routing surfaces. `find`/`grep`/`cat` are for operating on a *confirmed known file*, not for finding 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..2e6b769 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, usually swallowed 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 miss is visible. +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). + +`find`/`grep`/`cat` over `research/entities/` are for operating on a *confirmed known file*, never for *finding what's relevant*. The user should never have to tell an agent to use `/kg` instead of grepping the substrate. + --- ## P7 — Skill Freshness Check From 3e63cc4b6e371732176fc35c1ae9d5f4666cc5bf Mon Sep 17 00:00:00 2001 From: "Carlos D. Escobar-Valbuena" Date: Mon, 8 Jun 2026 11:24:30 -0500 Subject: [PATCH 2/2] docs(P6): tighten retrieval-reflex carve-out + equalize masking examples (P20 review) Cross-review (SHIP) flagged two wording MINORs: the carve-out could be read as a blanket substrate-grep ban, and the silent-miss masking examples differed across surfaces. Name the legitimate non-discovery greps (confirmed known file, tooling/skill internals incl. /kg's own body-grep + bookkeeping lint/index, bulk edits/counting) so it can't be over-read; equalize the masking set across primitives.md + template + workspace AGENTS.md. BRO-1426 Co-Authored-By: Claude Opus 4.8 (1M context) --- assets/templates/AGENTS.md.template | 2 +- references/primitives.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/assets/templates/AGENTS.md.template b/assets/templates/AGENTS.md.template index 8988057..ba2474e 100644 --- a/assets/templates/AGENTS.md.template +++ b/assets/templates/AGENTS.md.template @@ -92,7 +92,7 @@ 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** (typically masked by `2>/dev/null`), so the agent reasons over a *false-complete* context, and hand-picked slugs miss the relevant entities the catalog routing surfaces. `find`/`grep`/`cat` are for operating on a *confirmed known file*, not for finding what's relevant. +**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) diff --git a/references/primitives.md b/references/primitives.md index 2e6b769..d282437 100644 --- a/references/primitives.md +++ b/references/primitives.md @@ -129,10 +129,10 @@ The reflexive trigger rule above is the *write* side of the knowledge graph; thi **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, usually swallowed 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 miss is visible. +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). -`find`/`grep`/`cat` over `research/entities/` are for operating on a *confirmed known file*, never for *finding what's relevant*. The user should never have to tell an agent to use `/kg` instead of grepping the substrate. +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. ---