Looted · Looted · May 7, 2026 · Apr 24, 2026 · Apr 24, 2026 · Apr 24, 2026
diff --git a/.changeset/brave-buns-breathe.md b/.changeset/brave-buns-breathe.md
@@ -0,0 +1,8 @@
+---
+"kibi-opencode": patch
+---
+
+OpenCode bootstrap command support is now more reliable in fresh CI and Bun installations. The plugin can detect native `/init-kibi` command support when OpenCode installs the SDK as a transitive dependency of the plugin, preventing supported hosts from silently falling back to the namespaced MCP prompt.
+
+- Resolve `@opencode-ai/sdk` metadata from Bun's plugin-sibling dependency layout during native command capability detection.
+- Add regression coverage for the transitive SDK resolution path used by fresh installs.
diff --git a/.changeset/quiet-symbols-check.md b/.changeset/quiet-symbols-check.md
@@ -0,0 +1,8 @@
+---
+"kibi-cli": patch
+---
+
+Kibi now makes symbol manifest tracking harder to forget. New projects initialized with `kibi init` get a default `documentation/symbols.yaml`, and the managed pre-commit hook blocks commits when that manifest has unstaged changes so refreshed coordinates are committed with the related work.
+
+- Create the default symbol manifest during `kibi init` when it is missing.
+- Add a pre-commit guard that requires dirty `documentation/symbols.yaml` changes to be staged before `kibi check --staged` runs.
diff --git a/.gitignore b/.gitignore
@@ -51,4 +51,5 @@ documentation/tests/e2e/packed/.compiled/
 .kb/branches/*/sync-cache.json
 #! bun.lock
 .sisyphus
+.kb/briefs/
 .env
diff --git a/.opencode/kibi.json b/.opencode/kibi.json
@@ -0,0 +1,46 @@
+{
+  "enabled": true,
+  "prompt": {
+    "enabled": true,
+    "hookMode": "auto"
+  },
+  "sync": {
+    "enabled": true,
+    "debounceMs": 2000
+  },
+  "ux": {
+    "toastStartup": true,
+    "toastFailures": true,
+    "toastSuccesses": false,
+    "toastCooldownMs": 10000,
+    "briefs": {
+      "autoSubmit": true
+    }
+  },
+  "guidance": {
+    "dynamic": true,
+    "warnOnKbEdits": true,
+    "factFirstDomainRouting": true,
+    "commentDetection": {
+      "enabled": true,
+      "minLines": 6
+    },
+    "targetedChecks": {
+      "enabled": true
+    },
+    "sessionSummary": {
+      "enabled": true,
+      "logIntervalMs": 1800000
+    },
+    "smartEnforcement": {
+      "enabled": true,
+      "mode": "advisory",
+      "preflightTtlMs": 600000,
+      "idleResetMs": 1800000,
+      "degradedMode": "warn-once",
+      "requireRootKbForStrict": true,
+      "completionReminder": true
+    }
+  },
+  "logLevel": "info"
+}
diff --git a/AGENTS.md b/AGENTS.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -127,6 +127,8 @@ This applies to TypeScript (`.ts`, `.tsx`) and JavaScript (`.js`, `.jsx`) files
 
 If you ran `kibi init`, a pre-commit hook will automatically check your staged changes for missing requirement links. If any new or modified symbols are not linked to a requirement, your commit will be blocked with an error message. To proceed, add the appropriate `implements REQ-xxx` directive to your code.
 
+The hook also blocks commits when `documentation/symbols.yaml` has unstaged changes. Stage and commit the refreshed manifest with the code or documentation change that caused it.
+
 You can test your staged changes manually with:
 
 ```bash

diff --git a/README.md b/README.md
@@ -153,7 +153,7 @@ npx kibi status
 npx kibi check
 ```
 
-> **Note:** `kibi init` installs git hooks by default. Hooks automatically sync your KB on branch checkout and merge.
+> **Note:** `kibi init` installs git hooks by default and writes `.kb/` + `.kb/briefs/` ignore entries to `.gitignore`. Hooks automatically sync your KB on branch checkout and merge.
 
 ### Typical discovery workflow
 

diff --git a/bun.lock b/bun.lock
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
@@ -9,14 +9,16 @@ Initializes a kibi project in the current directory.
 **Behavior:**
 - Creates `.kb/` directory structure
 - Installs git hooks (pre-commit, post-checkout, post-merge, post-rewrite) by default
-- Adds `.kb/` to `.gitignore`
+- Adds `.kb/` and `.kb/briefs/` to `.gitignore`
 - Creates default `config.json` with document path patterns
+- Creates `documentation/symbols.yaml` when it does not already exist
 
 **Flags:**
 - `--no-hooks` - Skip git hook installation (hooks are installed by default)
 
 **Notes:**
 - Hooks are installed by default. Only use `--no-hooks` if you specifically don't want automated syncing.
+- The pre-commit hook blocks commits when `documentation/symbols.yaml` has unstaged changes, forcing refreshed symbol coordinates to be staged with the related code changes.
 - Idempotent: safe to run multiple times
 - After running, see the quick start guide in README.md for next steps
 

diff --git a/docs/install.md b/docs/install.md
@@ -154,7 +154,7 @@ If you encounter problems with SWI-Prolog:
 After installing kibi and verifying SWI-Prolog:
 
 1. Verify your environment: `npx kibi doctor`
-2. Initialize your project: `npx kibi init`
+2. Initialize your project: `npx kibi init` (installs hooks by default and adds `.kb/` + `.kb/briefs/` to `.gitignore`)
 3. Import documentation: `npx kibi sync`
 4. Explore the KB: `npx kibi search <query>`
 5. Inspect branch freshness: `npx kibi status`

diff --git a/docs/mcp-reference.md b/docs/mcp-reference.md
@@ -8,14 +8,14 @@ The public MCP surface is intentionally curated. Agents can call exact lookup, d
 
 ### `kb_autopilot_generate`
 
-Discover existing repository entities and bootstrap the KB via read-only candidate generation. Prefer this for day-0 activation.
+Discover existing repository entities and bootstrap the KB via read-only candidate synthesis. Use this as the backend for the interactive `/init-kibi` onboarding workflow.
 
 **Parameters:**
 - `limit` (optional): Max results per entity type
 - `include` (optional): Filter by file pattern
 
 **Returns:**
-Grouped candidate entities ready for review. Candidates must be explicitly applied via `kb_upsert` after validation.
+Grouped candidate entities synthesized from declared context and codebase evidence. Candidates must be explicitly applied via `kb_upsert` after user preview and approval.
 
 ### `kb_briefing_generate`
 
@@ -210,7 +210,7 @@ Validation report with any violations found and suggested fixes.
 
 ### `/init-kibi`
 
-Use this prompt for day-0 KB activation. It guides agents through `kb_autopilot_generate`, review, sequential `kb_upsert`, and validation.
+Interactive onboarding workflow for day-0 KB activation. It guides agents to ask at most 4 bounded questions to gather declared context, call `kb_autopilot_generate` for read-only synthesis, present a preview for user approval, and perform sequential `kb_upsert` followed by `kb_check`.
 
 ### `/brief-kibi`
 
@@ -226,7 +226,7 @@ Use this prompt at task start when you need a briefing grounded in current KB ev
 
 ## Recommended Agent Workflow
 
-1. **Day-0 Activation**: Use `kb_autopilot_generate` to discover entities and bootstrap the KB. Review candidates before applying.
+1. **Interactive Bootstrap**: Start with the `/init-kibi` workflow to gather declared context and synthesize entities. Always preview candidates for user approval before applying.
 2. **Start-task Briefing**: Use `kb_briefing_generate` or `/brief-kibi` when you need a citation-backed briefing before risky work.
 3. **Gather Context**: Use `kb_search` for discovery and `kb_query` for exact follow-up.
 4. **Inspect Freshness**: Use `kb_status` when branch or stale-state confidence matters.

diff --git a/docs/prompts/llm-rules.md b/docs/prompts/llm-rules.md
@@ -8,7 +8,7 @@ You are operating in a workspace that uses Kibi, an intelligent knowledge base s
 
 1. **Never manually read or edit files inside `.kb/`.** Interact with the knowledge base only through MCP tools.
 2. **Do not invoke `kibi` CLI commands directly from the agent.** Use MCP tools and sanctioned slash commands instead.
-3. **Start with \`kb_autopilot_generate\` for new repos, then use \`kb_search\`.** Use \`kb_autopilot_generate\` to discover entities and bootstrap the KB (preferred day-0 workflow). Use \`kb_search\` for broad discovery, then follow up with \`kb_query\` for exact IDs and precise lookups.
+3. **Start with interactive `/init-kibi` for new repos.** Use the `/init-kibi` slash command for an interactive onboarding workflow. This workflow uses `kb_autopilot_generate` to synthesize entities from your declared context and codebase evidence. Always preview candidates and get user approval before writing.
 4. **Create and update entities with `kb_upsert`.** Keep requirements, scenarios, symbols, tests, ADRs, flags, events, and facts synchronized with your work.
 5. **Use relationship rows during `kb_upsert`.** Link requirements, tests, symbols, and facts as part of the same write.
 6. **Never embed scenarios or tests inside requirement records.** Each requirement, scenario, and test **must** be a separate entity file. The canonical traceability chain is `REQ-xxx` → `SCEN-xxx` → `TEST-xxx`. Link them using explicit typed `links` entries or relationship rows (`specified_by`, `verified_by`, `validates`).

diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
@@ -93,6 +93,7 @@ If git operations don't trigger kibi hooks:
    ```bash
    kibi init
    ```
+   Re-running `kibi init` also refreshes `.gitignore` entries for `.kb/` and `.kb/briefs/`.
 
 ### Hook Conflicts
 

diff --git a/documentation/adr/ADR-020.md b/documentation/adr/ADR-020.md
@@ -0,0 +1,52 @@
+---
+id: ADR-020
+title: "Kibi Briefing v3 Architecture: Reliability through Session-Local Reconcile"
+status: proposed
+created_at: 2026-04-24T00:00:00Z
+updated_at: 2026-04-24T00:00:00Z
+source: documentation/adr/ADR-020.md
+priority: must
+tags:
+  - opencode
+  - architecture
+  - briefing
+  - reliability
+links:
+  - type: relates_to
+    target: ADR-016
+  - type: relates_to
+    target: ADR-019
+  - type: relates_to
+    target: REQ-opencode-kibi-briefing-v3
+---
+
+## Context
+
+Kibi Briefing v2 relied on a fast-path `file.edited` trigger that was susceptible to drift and stale state, especially when multiple files were edited or the context window diverged from the background worker's snapshot. Reliability issues were identified in complex multi-step sessions where the "briefing" state became detached from the actual agent workspace.
+
+## Decision
+
+We will implement a **Session-Local Reconcile** architecture for Kibi Briefing v3.
+
+1.  **Authoritative Inputs**: The briefing engine will treat the plugin-local **current-session** scope as the authoritative source of truth.
+2.  **Reconcile Model**: The plugin will implement a reconcile mechanism that compares the local session state (including uncommitted edits and session history) with the KB snapshot before generating a briefing.
+3.  **Baseline Clearing**: On branch switch or explicit session reset, the briefing state must be cleared to its baseline, ensuring no stale context persists.
+4.  **Multi-File Fingerprinting**: Context fingerprints will be calculated using a multi-file hash of all currently edited/dirty files in the session, rather than just the last edited file.
+5.  **Event Flow Preservation**:
+    - `file.edited` remains a fast-path hint to trigger a potential reconcile.
+    - `system.transform` remains text-only but may trigger a reconcile/fetch fallback if the current fingerprint is missing or stale.
+6.  **Fallback Preservation**: The `/brief-kibi` manual command remains the canonical escape hatch for users/agents to force a fresh briefing generation.
+7.  **MCP-Only Surface**: All briefing generation and reconciliation logic continues to be exposed via the `kb_briefing_generate` MCP tool. No forbidden CLI commands are introduced.
+
+## Rationale
+
+-   **Accuracy**: By grounding the briefing in the actual session state, we eliminate the primary source of drift.
+-   **Stability**: Multi-file fingerprinting ensures the briefing remains stable even as the agent bounces between related files.
+-   **Security**: Preserves the thin-host boundary (ADR-016) by keeping complex logic in the MCP/CLI layer while the plugin handles state synchronization.
+-   **Predictability**: Explicit baseline clearing prevents "context leakage" between different workstreams or branches.
+
+## Verification
+
+-   Verify that `kb_briefing_generate` accepts session-local state for reconciliation.
+-   Verify that context fingerprints accurately reflect the state of all dirty files in the session.
+-   Verify that switching branches triggers a complete clearing of the briefing cache.
diff --git a/documentation/facts/FACT-011.md b/documentation/facts/FACT-011.md
@@ -9,12 +9,7 @@ tags:
   - testing
   - flakiness
   - test-pollution
-fact_kind: property_value
-subject_key: kibi.kb.scope
-property_key: scope_model
-operator: eq
-value_type: string
-value_string: per_branch
+fact_kind: observation
 ---
 
 The kibi test suite has flaky integration tests that fail when run together but pass when run in isolation:

diff --git a/documentation/facts/FACT-ADR-SUPERSESSION-CHAIN.md b/documentation/facts/FACT-ADR-SUPERSESSION-CHAIN.md
@@ -0,0 +1,18 @@
+---
+id: FACT-ADR-SUPERSESSION-CHAIN
+title: ADR Supersession Chain Semantics
+status: active
+created_at: 2026-04-24T00:00:00Z
+updated_at: 2026-04-24T00:00:00Z
+source: documentation/facts/FACT-ADR-SUPERSESSION-CHAIN.md
+tags: [adr, schema]
+fact_kind: property_value
+subject_key: kibi.adr.supersession
+property_key: chain_semantics
+operator: eq
+value_type: string
+value_string: full_decision_history
+polarity: require
+---
+
+supersedes(adr, adr) relationship chains represent the full architectural decision history.
diff --git a/documentation/facts/FACT-ADR-TEMPORAL-INFERENCE-RULES.md b/documentation/facts/FACT-ADR-TEMPORAL-INFERENCE-RULES.md
@@ -0,0 +1,18 @@
+---
+id: FACT-ADR-TEMPORAL-INFERENCE-RULES
+title: ADR Temporal Inference Rules
+status: active
+created_at: 2026-04-24T00:00:00Z
+updated_at: 2026-04-24T00:00:00Z
+source: documentation/facts/FACT-ADR-TEMPORAL-INFERENCE-RULES.md
+tags: [adr, inference, temporal]
+fact_kind: property_value
+subject_key: kibi.adr.temporal_inference
+property_key: inference_surface
+operator: eq
+value_type: string
+value_string: current_adr_1_adr_chain_2_superseded_by_2
+polarity: require
+---
+
+Inference exposes current_adr/1, adr_chain/2, and superseded_by/2 predicates.
diff --git a/documentation/facts/FACT-AUDIT-APPEND-ONLY.md b/documentation/facts/FACT-AUDIT-APPEND-ONLY.md
@@ -3,11 +3,16 @@ id: FACT-AUDIT-APPEND-ONLY
 title: Append-Only Audit History
 status: active
 created_at: 2026-02-20T14:40:00Z
-updated_at: 2026-02-20T14:40:00Z
+updated_at: 2026-04-24T00:00:00Z
 source: documentation/facts/FACT-AUDIT-APPEND-ONLY.md
 tags: [audit, history]
-fact_kind: subject
-subject_key: kibi.audit.append_only
+fact_kind: property_value
+subject_key: kibi.write.governance
+property_key: audit_history_mode
+operator: eq
+value_type: string
+value_string: append_only
+polarity: require
 ---
 
 Audit history is append-only to preserve write provenance.
diff --git a/documentation/facts/FACT-BRANCH-INITIALIZATION.md b/documentation/facts/FACT-BRANCH-INITIALIZATION.md
@@ -3,11 +3,16 @@ id: FACT-BRANCH-INITIALIZATION
 title: Branch KB Initialization
 status: active
 created_at: 2026-02-20T14:40:00Z
-updated_at: 2026-02-20T14:40:00Z
+updated_at: 2026-04-24T08:12:00Z
 source: documentation/facts/FACT-BRANCH-INITIALIZATION.md
 tags: [branching, initialization]
-fact_kind: subject
-subject_key: kibi.branch.initialization
+fact_kind: property_value
+subject_key: kibi.kb.branch
+property_key: initialization_mode
+operator: eq
+value_type: string
+value_string: automatic
+polarity: require
 ---
 
 When a branch KB is missing, initialization logic creates it automatically.
-Original file line number
+Diff line change
@@ Expand Up @@
     If you ran `kibi init`, a pre-commit hook will automatically check your staged changes for missing requirement links. If any new or modified symbols are not linked to a requirement, your commit will be blocked with an error message. To proceed, add the appropriate `implements REQ-xxx` directive to your code.
+    The hook also blocks commits when `documentation/symbols.yaml` has unstaged changes. Stage and commit the refreshed manifest with the code or documentation change that caused it.
     You can test your staged changes manually with:
     ```bash
@@ Expand Down @@