feat(kb): AI-native representation Phase 3 — maintenance + backfill — 0.24.3

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "second-brain",
       "source": "./",
       "description": "Self-evolving AI second brain. Auto-learns from sessions, discovers tools, maintains a local knowledge base, and self-critiques code quality.",
-      "version": "0.24.2"
+      "version": "0.24.3"
     }
   ]
 }

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "second-brain",
   "description": "Self-evolving AI second brain. Automatically learns from sessions, discovers tools, maintains a local knowledge base, and self-critiques code quality — getting smarter with every interaction.",
-  "version": "0.24.2",
+  "version": "0.24.3",
   "author": {
     "name": "second-brain"
   },

agents/dream-runner.md

@@ -89,6 +89,12 @@ Phases 1–6 work ONLY on `~/.second-brain/dreams/{dream_id}/staging/wiki/`.
   frontmatter edits (the next reindex overwrites them).
 - Remove session-narrative noise
 - Optimize frontmatter for BM25 retrieval (title 3×, description 2×, tags 2×)
+- **AI-blocks (surface-only; skip if `SB_DREAM_AI_BLOCKS=off`)** — count staging structured
+  pages (learnings/decisions/entities/issues/concepts/security) lacking an `<!-- ai:begin -->`
+  block. **Do NOT author blocks in staging** — authoring stays a single path through the live
+  **knowledge-maintainer** (it grounds the block in current prose; the dream would re-derive
+  from prose it is still rewriting). Surface the count in the report: "N structured pages have
+  no ai-block — run `/second-brain:maintain` to backfill."
 
 **Phase 5: SUMMARIZE** (skip if `SB_DREAM_SUMMARIZE=off`)
 - Cluster the staging wiki's link graph and write one theme page per cluster, so a fresh

agents/knowledge-maintainer.md

@@ -220,6 +220,59 @@ The knowledge search uses BM25 with field weights: **title 3×, description 2×,
 - **Description**: what the source covers
 - **Body**: why it's relevant, key takeaways
 
+## Phase 4b: AI-block authoring / backfill (machine-first shared intermediate)
+
+Each structured page should carry an `<!-- ai:begin … ai:end -->` block — the schema'd,
+machine-first summary an AI reads instead of re-deriving the page from prose. The extractor
+authors it at capture; you **backfill** pages that predate the feature and **refresh** stale
+ones. This is the same per-category understanding Phase 4 just applied, emitted as the closed
+schema (one source of truth for "what a good X page contains").
+
+1. **Get the deterministic work-list** (blockless, substantive, structured pages):
+   ```bash
+   bash "$CLAUDE_PLUGIN_ROOT/scripts/kb-ai-block-candidates.sh" --knowledge-dir "$KD"
+   ```
+   Each TSV row is `<type>\t<slug>\t<path>`. A page that already has a block is skipped
+   (idempotent); the script never mutates.
+
+2. **For each candidate** — closed vocabulary: only the **six structured types** `learnings,
+   decisions, entities, issues, concepts, security` (schemas below; never invent a field or a
+   type):
+   - Read the page body. **Extract** field values from the EXISTING prose + frontmatter only.
+     **Never invent / hallucinate** a value — a field you can't ground in the page is left
+     unset (the block is gentle/optional). Values are SHORT plain-text propositions, never
+     `[[wiki-links]]` (relations live in the edge graph).
+   - Schemas: `learnings`: claim, trigger, action, scope, evidence, supersedes · `decisions`:
+     context, choice, alternatives, rationale, status, supersedes · `entities`: identity,
+     current_state, depends_on, owns, status · `issues`: symptom, cause, fix, severity, status
+     · `concepts`: problem, solution, where_applied, tradeoffs · `security`: threat,
+     mitigation, scope, status.
+   - **Render** the region deterministically (closed-vocab post-filter + marker-token
+     neutralization handled by `renderAiBlock` — do not hand-format the markers):
+     ```bash
+     jq -nc --arg t "<type>" --argjson b '<block-json>' '{type:$t,block:$b}' \
+       | node "$CLAUDE_PLUGIN_ROOT/mcp/dist/tools/ai-block-render-cli.bundle.js"
+     ```
+     `<block-json>` must be a valid JSON object of `"field": "short value"` pairs (omit
+     ungrounded fields), e.g. `{"claim":"…","action":"…"}`. On malformed input `jq`/the CLI emit
+     **nothing** (fail-safe) — confirm the rendered region is non-empty before the `Edit`.
+   - **Inject** the rendered region with `Edit`: between the frontmatter close (`---`) and the
+     first `# Heading`. Replace an existing region in place (refresh); never add a second.
+   - **Self-check**: a follow-up `knowledge_validate` run must show no new `ai_block_incomplete`
+     /`ai_block_missing` for the page (required fields you genuinely couldn't ground stay a
+     gentle `validateAiBlock` warning — that's fine; do NOT fabricate a value to silence it).
+
+3. **Budget**: each block authored counts as **one change against the 50/run cap** (unlike the
+   Phase 1 autofix sweep, which is uncounted). If candidates exceed the remaining budget, author
+   the highest-value first and **report the rest for the next run** — never exceed the cap.
+
+**Boundary:** Phase 4b runs **only on an explicit `/second-brain:maintain`** (the user asks to
+"maintain" / "clean up" the KB) — a **threshold/auto-dispatched** maintenance run (see
+*Autonomous Dispatch* below) **skips Phase 4b**, and it is never triggered by extraction or dream
+output directly. Bulk-authoring page content stays deliberate and reviewed, not unattended (the
+§5b automation boundary). Never author blocks for non-structured types or generated
+`projects/`/`themes/` pages.
+
 ## Phase 5: REINDEX
 
 1. Regenerate `wiki/index.md` via `knowledge_reindex` MCP tool
@@ -270,3 +323,10 @@ This agent should be dispatched:
 - When the user asks to "clean up" or "maintain" the knowledge base
 
 The agent is self-sufficient. It reads the hot tier and wiki, identifies all work across all 6 phases, executes in order, and reports results. No human input needed during execution.
+
+**Exception — Phase 4b (ai-block authoring/backfill):** an **auto-dispatched** run (the
+`SB_MAINTAINER_THRESHOLD` wiki-write counter, a `knowledge_reindex`-issues trigger, or
+post-extraction) performs the consolidation phases (1–4, 5, 6) but **skips Phase 4b** —
+backfilling ai-blocks bulk-authors page content, so it is **explicit-invocation only** (a
+deliberate `/second-brain:maintain` or "maintain/clean up the KB" request). Unattended runs never
+bulk-author blocks; this keeps the auto-dispatch lightweight and the §5b automation boundary intact.