diff --git a/CHANGELOG.md b/CHANGELOG.md index 067942c..5a3975a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,37 @@ # Changelog +## 0.12.0 — 2026-05-21 + +### LLM-as-index wiring — catalog refresh hook + `/kg load` skill doctor checks (BRO-1223) + +Wires the workspace-side LLM-as-index architecture into bstack's bootstrap and audit machinery. The workspace ships a Stop hook that regenerates `docs/knowledge-index.md` after each session (so the dense catalog stays fresh without manual `bookkeeping index` invocations) and a Claude skill `/kg load ` that uses the catalog to route the loading agent. + +The architectural anchor: at sub-10k-entity scale, the substrate (`research/entities/**/*.md`) fits in any 1M-context model with >95% headroom — the LLM **is** the index. One projection (the catalog), one consumer (the loading agent), inferences fold back into the substrate as commits. No SQLite mirror, no embeddings, no typed-edge schema. + +- **CHANGED** `assets/templates/settings.json.snippet` — adds a second `Stop` hook entry pointing at `${BROOMVA_WORKSPACE}/scripts/knowledge-catalog-refresh-hook.sh`, tagged `_bstack_primitive: "P6"`. New installs and `bstack repair` invocations now wire the catalog refresh by default. Composes cleanly with the existing `conversation-bridge-hook.sh` Stop entry — bridge first, catalog second. +- **CHANGED** `scripts/doctor.sh` — section 7 (Primitive mechanisms) gains three new P6 sub-checks: + - `scripts/knowledge-catalog-refresh-hook.sh` present + executable + - `docs/knowledge-index.md` exists AND mtime ≤ 48h (catalog freshness gate; warns at >48h with the repair command) + - `~/.claude/skills/kg/SKILL.md` + `scripts/kg.py` present (the load skill) + + All three are advisory (informational nudges) — they never fail strict-mode CI on missing-skill, because the kg skill is intentionally workspace-local v1 (no GitHub repo, no skills-lock entry) until rule-of-three earns the promotion. + +### Cross-repo composition + +This release pairs with two workspace-side PRs: +- `broomva/bookkeeping` — adds `cmd_index` (the catalog generator) + `from __future__ import annotations` Py3.9 compatibility fix +- `broomva/broomva` — adds the Stop hook script, wires `.claude/settings.json`, adds AGENTS.md §P6 sub-rule on substrate-edit-as-inference-persistence, ships the `/kg load` skill at `~/.claude/skills/kg/`, mirrors documentation at `docs/skills/kg.md` + +### Validation gate + +The composite release is validated by the **12-query parity test** documented in the PR body: each of 12 representative graph queries (tag intersection, k-hop neighborhood, shortest path, provenance trace, hub identification, full-text body search, cross-type co-occurrence, etc.) must be answerable by the agent using only `/kg load` + on-demand entity reads, matching the deterministic Python-script baseline. + +### Future work + +- Promote `broomva/kg` to its own GitHub repo + bstack skills-lock entry once usage exceeds rule-of-three (≥3 sessions with load-bearing `/kg load` invocations) +- Add `bookkeeping index --cache-graph` to memoize the parsed in-memory graph to `~/.cache/broomva/bookkeeping/graph.json` (drops repeat runs from ~315ms to ~5ms) +- Optional sidecar embeddings index at >2k entities (not needed today; pre-mature now) + ## 0.11.0 — 2026-05-20 ### Live mode for `bstack bench` — Databricks Gateway provider + OpenAI-compatible abstraction (BRO-1211) diff --git a/VERSION b/VERSION index d9df1bb..ac454c6 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.11.0 +0.12.0 diff --git a/assets/templates/settings.json.snippet b/assets/templates/settings.json.snippet index 6d2e5b6..835301c 100644 --- a/assets/templates/settings.json.snippet +++ b/assets/templates/settings.json.snippet @@ -45,6 +45,13 @@ "command": "${BROOMVA_WORKSPACE}/scripts/conversation-bridge-hook.sh", "timeout": 5, "_bstack_primitive": "P1" + }, + { + "type": "command", + "command": "${BROOMVA_WORKSPACE}/scripts/knowledge-catalog-refresh-hook.sh", + "timeout": 5, + "_bstack_primitive": "P6", + "_purpose": "Regenerate dense LLM-loadable catalog (LLM-as-index architecture; routes /kg load)" } ] } diff --git a/scripts/doctor.sh b/scripts/doctor.sh index 34f762d..143147c 100755 --- a/scripts/doctor.sh +++ b/scripts/doctor.sh @@ -270,6 +270,44 @@ else "install/rebuild from bstack repo HEAD" fi +# P6 catalog: knowledge-catalog-refresh-hook + docs/knowledge-index.md freshness +# (LLM-as-index architecture — substrate routes through the catalog; the +# catalog must regenerate at Stop time and stay <48h old) +_CATALOG_HOOK="$WORKSPACE/scripts/knowledge-catalog-refresh-hook.sh" +_CATALOG="$WORKSPACE/docs/knowledge-index.md" +if [ -x "$_CATALOG_HOOK" ]; then + ok "P6 catalog hook: scripts/knowledge-catalog-refresh-hook.sh present + executable" +else + gap "P6 catalog hook missing or not executable: scripts/knowledge-catalog-refresh-hook.sh" \ + "copy from bstack/assets/templates/ or rerun 'bstack repair'" +fi +if [ -f "$_CATALOG" ]; then + if [ "$(uname)" = "Darwin" ]; then + _catalog_mtime=$(stat -f %m "$_CATALOG" 2>/dev/null || echo 0) + else + _catalog_mtime=$(stat -c %Y "$_CATALOG" 2>/dev/null || echo 0) + fi + _now=$(date +%s) + _age_h=$(( (_now - _catalog_mtime) / 3600 )) + if [ "$_age_h" -le 48 ]; then + ok "P6 catalog fresh: docs/knowledge-index.md (${_age_h}h old)" + else + gap "P6 catalog stale: docs/knowledge-index.md (${_age_h}h old; threshold 48h)" \ + "run 'python3 skills/bookkeeping/scripts/bookkeeping.py index'" + fi +else + gap "P6 catalog missing: docs/knowledge-index.md" \ + "run 'python3 skills/bookkeeping/scripts/bookkeeping.py index'" +fi + +# /kg load skill (Claude-installed at ~/.claude/skills/kg/ — workspace-local v1) +if [ -f "$HOME/.claude/skills/kg/SKILL.md" ] && [ -f "$HOME/.claude/skills/kg/scripts/kg.py" ]; then + ok "/kg load skill installed at ~/.claude/skills/kg/" +else + gap "/kg load skill missing at ~/.claude/skills/kg/" \ + "install per docs/skills/kg.md (workspace-local v1; promotes to broomva/kg GitHub repo after rule-of-three)" +fi + # ── L3 trust gates (G-L3-1 + G-L3-2) ─────────────────────────────────────── section "8. L3 trust gates" L3_PRIMITIVE_LINT="$WORKSPACE/scripts/bstack-primitive-lint.py"