kibi-opencode 0.19.4 → 2.0.0

package/dist/prompt.d.ts

@@ -1,8 +1,8 @@
 import type { CommentAnalysisResult } from "./comment-analysis.js";
 import type { KibiConfig } from "./config.js";
 import type { GuidanceCache } from "./guidance-cache.js";
-import { type InitKibiCommandCapability } from "./init-kibi-capability.js";
 import type { KbFreshnessEvaluation } from "./kb-freshness-state.js";
+import { type KibiBootstrapCommandCapability } from "./kibi-bootstrap-capability.js";
 import type { PathKind } from "./path-kind.js";
 import type { RepoPosture } from "./repo-posture.js";
 import type { RiskClass } from "./risk-classifier.js";
@@ -55,13 +55,13 @@ export interface PromptContext {
     /** Paths changed for freshness evaluation (capped at 5) */
     freshnessChangedPaths?: string[];
 }
-export declare function postureGuidance(posture: RepoPosture, capability?: InitKibiCommandCapability): string | null;
+export declare function postureGuidance(posture: RepoPosture, capability?: KibiBootstrapCommandCapability): string | null;
 /**
  * Build prompt with contextual guidance based on posture, risk class, and cache state.
  */
-export declare function buildPrompt(context?: PromptContext, capability?: InitKibiCommandCapability): string;
+export declare function buildPrompt(context?: PromptContext, capability?: KibiBootstrapCommandCapability): string;
 /**
  * Inject prompt guidance if not already present.
  */
-export declare function injectPrompt(current: string, config: KibiConfig, context?: PromptContext, capability?: InitKibiCommandCapability): string;
+export declare function injectPrompt(current: string, config: KibiConfig, context?: PromptContext, capability?: KibiBootstrapCommandCapability): string;
 export { SENTINEL };

package/dist/prompt.js

@@ -1,6 +1,6 @@
 import * as path from "node:path";
 import { isPluginEnabled } from "./config.js";
-import { getInitKibiCommandCapability, } from "./init-kibi-capability.js";
+import { getKibiBootstrapCommandCapability, } from "./kibi-bootstrap-capability.js";
 import { getSourceLinkedRequirementIds } from "./source-linked-guidance.js";
 const SENTINEL = "<!-- kibi-opencode -->";
 // ── Token budget enforcement ───────────────────────────────────────────
@@ -56,17 +56,17 @@ function deriveFileBucket(pathKind) {
 function getFocusEdit(context) {
     return (context.focusEdit ?? context.recentEdits[context.recentEdits.length - 1]);
 }
-function buildInitKibiBootstrapReference(capability = getInitKibiCommandCapability()) {
+function buildKibiBootstrapReference(capability = getKibiBootstrapCommandCapability()) {
     if (capability.supported) {
-        return "Bootstrap existing repos: when the Kibi OpenCode plugin is active and native injection is supported, `/init-kibi` is the canonical short alias; `/kibi:init-kibi:mcp` remains the namespaced MCP fallback for the retroactive initialization (`kb_autopilot_generate`) workflow.";
+        return "Bootstrap existing repositories with `/kibi-bootstrap`; the canonical `kibi-bootstrap` skill owns planner, approval, apply, and repair semantics.";
     }
-    return "Bootstrap existing repos: this host does not support native `/init-kibi` injection, so Kibi must fail closed and does not register a fake native alias; use `/kibi:init-kibi:mcp` for the retroactive initialization (`kb_autopilot_generate`) workflow.";
+    return "This host cannot inject native `/kibi-bootstrap`; use `/kibi:kibi-bootstrap:mcp` to route to the canonical `kibi-bootstrap` skill.";
 }
-function buildBootstrapRequiredBody(capability = getInitKibiCommandCapability()) {
-    const commandBullet = capability.supported
-        ? "- When the Kibi OpenCode plugin is active and native injection is supported, use `/init-kibi` as the canonical short alias; `/kibi:init-kibi:mcp` remains the namespaced MCP fallback."
-        : "- This host does not support native `/init-kibi` injection. Kibi must fail closed and does not register a fake native alias; use `/kibi:init-kibi:mcp` instead.";
-    return `Kibi capability selection (MCP tools and the trusted project-local CLI are peer surfaces over the same 18 operations):\n1. If Kibi MCP tools are visible and approved, use MCP.\n2. Otherwise, in a trusted workspace, use the project-local CLI's dedicated JSON routes with \`--input <file|->\`.\n3. If neither interface is available, Kibi operation is blocked; tell the operator.\nDo not infer MCP availability from config file existence. Do not read or edit \`.kb/\` files directly. Query before mutate. Run \`kb_upsert\` sequentially. Run \`kb_check\` before completion.\n\nThis repository does not appear to have Kibi initialized. Agents should:\n${commandBullet}\n- The workflow uses \`kb_autopilot_generate\` for read-only synthesis; always preview and get approval before writes.\n- Ask the operator to handle setup or repair if bootstrap is insufficient.\n- Load \`kibi-usage\` with \`kb_skills_load\` for comprehensive guidance.`;
+function buildBootstrapRequiredBody(capability = getKibiBootstrapCommandCapability()) {
+    const command = capability.supported
+        ? "Use `/kibi-bootstrap`."
+        : "Use `/kibi:kibi-bootstrap:mcp`; this host does not support native command injection.";
+    return `Kibi infrastructure is not initialized. Run \`kibi init\`, then inspect \`kb_status.bootstrap.nextAction\` and route the explicit bootstrap request to the canonical \`kibi-bootstrap\` skill. ${command}`;
 }
 function buildHardGateBlock(block) {
     const pathLines = block.shownPaths.map((path) => `- \`${path}\``);
@@ -80,18 +80,7 @@ function buildHardGateBlock(block) {
         reasonLine,
         "Affected files:",
         ...pathLines,
-        "Capability-based recovery steps:",
-        "- MCP tools and the trusted project-local CLI are peer surfaces over the same 18 operations; choose by what is visible and approved here.",
-        "- If Kibi MCP tools are visible and approved, use MCP.",
-        "- Otherwise, in a trusted workspace, use the project-local CLI's dedicated JSON routes with `--input <file|->`.",
-        "- If neither interface is available, Kibi operation is blocked; tell the operator to enable MCP or the trusted project-local CLI.",
-        "- Do not infer MCP availability from config file existence. Do not read or edit `.kb/` files directly.",
-        "- Query before mutate. Run `kb_upsert` sequentially. Run `kb_check` before completion.",
-        "- Run `kb_search` for impacted requirements, tests, ADRs, and facts.",
-        "- Run `kb_query` with `sourceFile` for each affected file.",
-        "- Run `kb_status` if branch or snapshot freshness matters.",
-        "- Run `kb_upsert` for required traceability, relationship, or fact updates.",
-        "- Run `kb_check` before continuing.",
+        "Inspect typed Kibi status `nextActions`, then route to the canonical kibi-usage, kibi-freshness, or kibi-traceability skill. Use the host-visible approved peer surface and never read or edit `.kb` directly.",
     ]
         .filter((line) => line !== null)
         .join("\n");
@@ -123,17 +112,13 @@ Production code: use \`implements\` (symbol→req) for requirement ownership. Te
 - \`covered_by\` is coverage evidence only
 - Prefer scenario-first: req→scenario→test when scenarios exist
 - Route durable knowledge comments to KB entities, not inline comments
-- documentation/symbols.yaml refresh is required when extraction output changes; do not revert as scope creep`,
+- .kb/symbols.yaml refresh is required when extraction output changes; do not revert as scope creep`,
     manual_kb_edit: `⚠️  **WARNING: Direct .kb/ edits bypass validation**
 
-The Kibi knowledge base is managed through visible MCP tools or the trusted project-local CLI — peer surfaces over the same 18 operations. Do not read or edit \`.kb/\` files directly.
-- Query before mutate and run kb_upsert sequentially
-- Use kb_upsert to create/update entities
-- Use kb_delete to remove entities
-- Use kb_check to validate consistency`,
+Do not read or edit \`.kb/\` directly. Follow typed Kibi status \`nextActions\` and route durable changes through the canonical kibi-usage, kibi-freshness, or kibi-traceability skill.`,
 };
 // ── Posture overrides ──────────────────────────────────────────────────
-export function postureGuidance(posture, capability = getInitKibiCommandCapability()) {
+export function postureGuidance(posture, capability = getKibiBootstrapCommandCapability()) {
     // implements REQ-opencode-prompt-injection
     switch (posture) {
         case "vendored_only":
@@ -146,7 +131,7 @@ ${buildBootstrapRequiredBody(capability)}`;
         case "root_partial":
             return `⚠️  **Partial KB setup detected**
 
-Root .kb/config.json exists but some configured KB targets are missing. Guidance remains advisory until the user/operator restores the configured KB targets.`;
+Root .kb/manifest.json exists but some canonical KB targets under .kb/ are missing. Guidance remains advisory until the user/operator restores the canonical layout.`;
         default:
             return null;
     }
@@ -155,7 +140,7 @@ Root .kb/config.json exists but some configured KB targets are missing. Guidance
 /**
  * Build prompt guidance block based on posture, risk class, and cache state.
  */
-function buildContextualGuidance(context, capability = getInitKibiCommandCapability()) {
+function buildContextualGuidance(context, capability = getKibiBootstrapCommandCapability()) {
     if (context.hardGateBlock) {
         return `${SENTINEL}\n\n${buildHardGateBlock(context.hardGateBlock)}`;
     }
@@ -437,7 +422,7 @@ function buildCommentSuggestionGuidance(suggestion) {
 Your recent code edit contains a comment that looks like a **strict domain fact** (invariants, properties, limits, defaults, or cardinality constraints).
 
 **Action**: Route to a FACT entity in the strict fact lane:
-- Create \`documentation/facts/FACT-xxx.md\` with the invariant (use \`constrains\` + \`requires_property\` for contradiction-safe reasoning)
+- Create \`.kb/facts/FACT-xxx.md\` with the invariant (use \`constrains\` + \`requires_property\` for contradiction-safe reasoning)
 - Bug/workaround notes: use \`fact_kind: observation\` or \`meta\` instead — these are non-blocking and excluded from contradiction inference
 - Link it to relevant requirements
 
@@ -448,7 +433,7 @@ This keeps domain truths centralized, searchable, and contradiction-safe.`;
 Your recent code edit contains a comment that looks like a **technical decision** (tradeoffs, rationale, or architecture choices).
 
 **Action**: Instead of inline comments, route this to an ADR entity:
-- Create \`documentation/adr/ADR-xxx.md\` documenting the decision
+- Create \`.kb/adr/ADR-xxx.md\` documenting the decision
 - Include context, options considered, and the chosen approach
 - Link to constrained code symbols
 
@@ -459,7 +444,7 @@ This preserves decision context for future maintainers.`;
 Your recent code edit contains a comment that looks like **behavior intent** (system capabilities or user-facing requirements).
 
 **Action**: Instead of inline comments, route this to a REQ entity:
-- Create \`documentation/requirements/REQ-xxx.md\` with the behavior description
+- Create \`.kb/requirements/REQ-xxx.md\` with the behavior description
 - Add SCEN and TEST entities for specification and verification
 - Link code: production uses \`implements\` (symbol→req) for ownership; test code uses \`executable_for\`; \`covered_by\` is coverage evidence only
 
@@ -478,41 +463,20 @@ Before implementing or explaining code:
 /**
  * Build the static guidance block (original behavior).
  */
-function buildBaseGuidance(capability = getInitKibiCommandCapability()) {
+function buildBaseGuidance(capability = getKibiBootstrapCommandCapability()) {
     return `${SENTINEL}
-This project uses Kibi through capability-selected MCP or CLI JSON routes. Prefer storing durable knowledge in Kibi over code comments.
+Use typed Kibi status and its \`nextActions\` as the workflow contract. Route general work to \`kibi-usage\`, freshness decisions to \`kibi-freshness\`, source proof to \`kibi-traceability\`, and an explicit bootstrap request to \`kibi-bootstrap\`. Use the host-visible approved Kibi peer surface; if it is unavailable, report the blocked capability. Never read or edit \`.kb/\` directly.
 
-Before changing behavior: use kb_search for discovery, then kb_query by sourceFile, id, type, or tags for exact follow-up; do not rely on undocumented tools.
-
-Keep changed symbols traceable: production code uses \`implements\` (symbol→req) for ownership; test code uses \`executable_for\`; \`covered_by\` is coverage evidence only. Inline \`// implements REQ-xxx\` comments remain backward-compatible.
-
-Kibi capability selection (MCP tools and the trusted project-local CLI are peer surfaces over the same 18 operations):
-1. If Kibi MCP tools are visible and approved, use MCP.
-2. Otherwise, in a trusted workspace, use the project-local CLI's dedicated JSON routes with \`--input <file|->\`.
-3. If neither interface is available, Kibi operation is blocked; tell the operator to enable MCP or the trusted project-local CLI.
-Do not infer MCP availability from config file existence. Do not read or edit \`.kb/\` files directly. Query before mutate. Run \`kb_upsert\` sequentially. Run \`kb_check\` before completion.
+Keep changed symbols traceable: production code uses \`implements\` (symbol→req) for ownership; test code uses \`executable_for\`; \`covered_by\` is coverage evidence only.
 
 Dogfood note for this repo: OpenCode here uses local built \`kibi-mcp\` and \`kibi-opencode\` artifacts. If you change package versions or local package wiring, run \`bun run build\` before relying on OpenCode in this workspace.
 
-**Kibi-first workflow:**
-1. **Discover**: Run kb_search for REQ, ADR, TEST, FACT. Decompose broad queries (e.g., "Apple Sign-In").
-2. **Confirm**: Run kb_query with sourceFile, id, type, or tags once you know the exact follow-up target.
-3. **Inspect freshness**: Run kb_status when branch or stale-state confidence matters.
-4. **Document intent**: If you are about to explain code, STOP. Route that explanation to kb_upsert instead of inline comments.
-5. **Link during work**: When creating KB entities, include relationship rows: specified_by (req→scenario), implements (symbol→req for ownership), covered_by (symbol→test for coverage), executable_for (test code→test).
-6. **Validate**: Run kb_check after KB mutations to catch violations early.
-7. **Before completion/commit**: Kibi impact evidence is required before completion/commit. If extraction output changes, refresh documentation/symbols.yaml and do not revert that update as scope creep.
-
-MCP and CLI expose the same 18 Kibi operations. Use the exact MCP tool or dedicated CLI route; do not invent a generic runner.
-
-For comprehensive Kibi usage guidance (relationships, fact lanes, workflows), use \`kb_skills_load\` with skill id \`kibi-usage\`.
-
-${buildInitKibiBootstrapReference(capability)}`;
+${buildKibiBootstrapReference(capability)}`;
 }
 /**
  * Build prompt with contextual guidance based on posture, risk class, and cache state.
  */
-export function buildPrompt(context, capability = getInitKibiCommandCapability()) {
+export function buildPrompt(context, capability = getKibiBootstrapCommandCapability()) {
     if (!context) {
         return buildBaseGuidance(capability).trim();
     }
@@ -521,7 +485,7 @@ export function buildPrompt(context, capability = getInitKibiCommandCapability()
 /**
  * Inject prompt guidance if not already present.
  */
-export function injectPrompt(current, config, context, capability = getInitKibiCommandCapability()) {
+export function injectPrompt(current, config, context, capability = getKibiBootstrapCommandCapability()) {
     if (!config.prompt.enabled || !isPluginEnabled(config)) {
         return current;
     }

package/dist/repo-posture.js

@@ -1,16 +1,16 @@
 // implements REQ-opencode-smart-enforcement-v1, REQ-opencode-kibi-plugin-v1
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join, resolve } from "node:path";
-// Default sync paths — must stay in sync with file-filter.ts DEFAULT_SYNC_PATHS
-const DEFAULT_SYNC_PATHS = {
-    requirements: "documentation/requirements/**/*.md",
-    scenarios: "documentation/scenarios/**/*.md",
-    tests: "documentation/tests/**/*.md",
-    adr: "documentation/adr/**/*.md",
-    flags: "documentation/flags/**/*.md",
-    events: "documentation/events/**/*.md",
-    facts: "documentation/facts/**/*.md",
-    symbols: "documentation/symbols.yaml",
+// Canonical Kibi knowledge targets — must stay in sync with kb-paths.ts.
+const CANONICAL_KB_TARGETS = {
+    requirements: ".kb/requirements",
+    scenarios: ".kb/scenarios",
+    tests: ".kb/tests",
+    adr: ".kb/adr",
+    flags: ".kb/flags",
+    events: ".kb/events",
+    facts: ".kb/facts",
+    symbols: ".kb/symbols.yaml",
 };
 // ── helpers ────────────────────────────────────────────────────────────
 function findVendoredTrees(cwd) {
@@ -19,7 +19,7 @@ function findVendoredTrees(cwd) {
         ["kibi", "opencode.json"],
         ["kibi", "package.json"],
         ["kibi", "packages", "mcp"],
-        ["kibi", "documentation"],
+        ["kibi", ".kb"],
     ];
     for (const marker of vendoredMarkers) {
         const markerPath = join(cwd, ...marker);
@@ -37,63 +37,22 @@ function findVendoredTrees(cwd) {
     }
     return [...new Set(results)];
 }
-/** Check if .kb/config.json exists at root. */
-function rootKbConfigExists(cwd) {
-    return existsSync(join(cwd, ".kb", "config.json"));
+/** Check if `.kb/manifest.json` exists at root. */
+function rootKbManifestExists(cwd) {
+    return existsSync(join(cwd, ".kb", "manifest.json"));
 }
-/** Read and parse .kb/config.json. Returns null on failure. */
-function readRootConfig(cwd) {
-    try {
-        return (JSON.parse(readFileSync(join(cwd, ".kb", "config.json"), "utf8")) || null);
-    }
-    catch {
-        return null;
-    }
-}
-/** Check if all configured KB targets resolve (directories / files exist). */
+/** Check if all canonical KB targets resolve (directories / files exist). */
 function rootTargetsAllResolve(cwd) {
-    const configPath = join(cwd, ".kb", "config.json");
-    let config = {};
-    try {
-        config = JSON.parse(readFileSync(configPath, "utf8")) || {};
-    }
-    catch {
-        return false;
-    }
-    const paths = config.paths;
-    const defaultKeys = [
-        "requirements",
-        "scenarios",
-        "tests",
-        "adr",
-        "flags",
-        "events",
-        "facts",
-        "symbols",
-    ];
-    for (const key of defaultKeys) {
-        const raw = paths?.[key] ?? DEFAULT_SYNC_PATHS[key];
+    for (const raw of Object.values(CANONICAL_KB_TARGETS)) {
         if (!raw)
             return false;
-        // Normalize: strip trailing slashes and glob patterns to get the root dir/file path
-        const normalized = raw.replace(/\/+$/, "");
-        const isFile = normalized.endsWith(".yaml") || normalized.endsWith(".yml");
+        const isFile = raw.endsWith(".yaml") || raw.endsWith(".yml");
         if (isFile) {
-            if (!existsSync(resolve(cwd, normalized)))
+            if (!existsSync(resolve(cwd, raw)))
                 return false;
         }
-        else {
-            // Strip first glob segment
-            const segments = normalized.split("/");
-            const rootSegments = [];
-            for (const seg of segments) {
-                if (seg.includes("*") || seg.includes("?") || seg.includes("["))
-                    break;
-                rootSegments.push(seg);
-            }
-            const dirPath = rootSegments.join("/") || ".";
-            if (!existsSync(resolve(cwd, dirPath)))
-                return false;
+        else if (!existsSync(resolve(cwd, raw))) {
+            return false;
         }
     }
     return true;
@@ -134,54 +93,42 @@ function hasRootKibiIntent(cwd) {
 }
 // ── main classifier ────────────────────────────────────────────────────
 export function detectPosture(cwd) {
-    const hasRootConfig = rootKbConfigExists(cwd);
+    const hasRootManifest = rootKbManifestExists(cwd);
     const vendoredTrees = findVendoredTrees(cwd);
-    // 1. hybrid_root_plus_vendored — root config AND vendored subtrees
-    if (hasRootConfig && vendoredTrees.length > 0) {
+    // 1. hybrid_root_plus_vendored — root manifest AND vendored subtrees
+    if (hasRootManifest && vendoredTrees.length > 0) {
         return {
             state: "hybrid_root_plus_vendored",
             needsBootstrap: false,
-            reason: `Root .kb/config.json exists alongside vendored tree(s): ${vendoredTrees.join(", ")}`,
+            reason: `Root .kb/manifest.json exists alongside vendored tree(s): ${vendoredTrees.join(", ")}`,
             maintenanceDegraded: false,
         };
     }
-    // 2-3. root config exists (check maintenance mode and target resolution)
-    if (hasRootConfig) {
-        const config = readRootConfig(cwd);
-        const maint = config?.maintenance;
-        const maintenanceDisabled = maint !== undefined && maint.enabled === false;
-        // maintenance_degraded overlay: maintenance explicitly disabled → root_active
-        if (maintenanceDisabled) {
-            return {
-                state: "root_active",
-                needsBootstrap: false,
-                reason: "Root .kb/config.json exists; maintenance mode explicitly disabled",
-                maintenanceDegraded: true,
-            };
-        }
+    // 2-3. root manifest exists (check target resolution)
+    if (hasRootManifest) {
         const allResolve = rootTargetsAllResolve(cwd);
         if (allResolve) {
             return {
                 state: "root_active",
                 needsBootstrap: false,
-                reason: "Root .kb/config.json exists and all configured KB targets resolve",
+                reason: "Root .kb/manifest.json exists and all canonical KB targets resolve",
                 maintenanceDegraded: false,
             };
         }
-        // 3. root_partial — root config exists but targets are missing
+        // 3. root_partial — manifest exists but targets are missing
         return {
             state: "root_partial",
             needsBootstrap: true,
-            reason: "Root .kb/config.json exists but some configured KB targets are missing",
+            reason: "Root .kb/manifest.json exists but some canonical KB targets are missing",
             maintenanceDegraded: false,
         };
     }
-    // 4. vendored_only — no root config, but vendored markers found
+    // 4. vendored_only — no root manifest, but vendored markers found
     if (vendoredTrees.length > 0) {
         return {
             state: "vendored_only",
             needsBootstrap: false,
-            reason: `No root .kb/config.json, but vendored Kibi tree(s) detected: ${vendoredTrees.join(", ")}`,
+            reason: `No root .kb/manifest.json, but vendored Kibi tree(s) detected: ${vendoredTrees.join(", ")}`,
             maintenanceDegraded: false,
         };
     }

package/dist/risk-classifier.d.ts

@@ -27,10 +27,10 @@ export interface RiskClassification {
  * Classify a file edit into a deterministic risk class.
  *
  * Classification order (first match wins):
- * 1. manual_kb_edit        — file is under .kb/
+ * 1. manual_kb_edit        — opaque/derived `.kb/` files (pathKind "kb")
  * 2. safe_test_only        — pathKind is "test"
- * 3. req_policy_candidate  — pathKind is "requirement"
- * 4. kb_doc_structural     — pathKind is "scenario", "adr", or "fact"
+ * 3. req_policy_candidate  — pathKind is "requirement" (including `.kb/requirements`)
+ * 4. kb_doc_structural     — pathKind is "scenario", "adr", "fact", "flag", "event", or "symbol"
  * 5. safe_docs_only        — pathKind is "unknown" (markdown/config/etc.)
  * 6. traceability_candidate — code with exports AND (hasDurableComment OR missing traceability)
  * 7. behavior_candidate    — code with exports, already has traceability, no durable comment

package/dist/risk-classifier.js

@@ -11,10 +11,10 @@ const TRACEABILITY_PATTERN = /implements\s+REQ-[A-Za-z0-9_-]+/i;
  * Classify a file edit into a deterministic risk class.
  *
  * Classification order (first match wins):
- * 1. manual_kb_edit        — file is under .kb/
+ * 1. manual_kb_edit        — opaque/derived `.kb/` files (pathKind "kb")
  * 2. safe_test_only        — pathKind is "test"
- * 3. req_policy_candidate  — pathKind is "requirement"
- * 4. kb_doc_structural     — pathKind is "scenario", "adr", or "fact"
+ * 3. req_policy_candidate  — pathKind is "requirement" (including `.kb/requirements`)
+ * 4. kb_doc_structural     — pathKind is "scenario", "adr", "fact", "flag", "event", or "symbol"
  * 5. safe_docs_only        — pathKind is "unknown" (markdown/config/etc.)
  * 6. traceability_candidate — code with exports AND (hasDurableComment OR missing traceability)
  * 7. behavior_candidate    — code with exports, already has traceability, no durable comment
@@ -22,11 +22,14 @@ const TRACEABILITY_PATTERN = /implements\s+REQ-[A-Za-z0-9_-]+/i;
  */
 export function classifyRisk(params) {
     const { pathKind, isUnderKb, hasMustPriority, hasDurableComment, fileContent, } = params;
-    // 1. manual_kb_edit — direct KB manipulation is always risky
-    if (isUnderKb) {
+    // 1. manual_kb_edit — derived/runtime `.kb/` files, not canonical lanes.
+    // Entity lanes under `.kb/` keep their typed pathKind (requirement, symbol, …).
+    if (isUnderKb && pathKind === "kb") {
         return {
             riskClass: "manual_kb_edit",
-            reasons: ["File is under .kb/ — manual edits bypass KB validation"],
+            reasons: [
+                "File is opaque or derived `.kb/` runtime state — manual edits bypass KB validation",
+            ],
         };
     }
     // 2. safe_test_only — test files are low-risk

package/dist/scheduler.js

@@ -256,7 +256,7 @@ async function runKibiSync(worktree) {
                         ? `${error.message}${signal}`
                         : signal || undefined;
                     resolve({
-                        exitCode: error.code ?? 1,
+                        exitCode: typeof error.code === "number" ? error.code : 1,
                         syncCommand: "kibi sync",
                         ...(truncatedOut !== undefined ? { syncStdout: truncatedOut } : {}),
                         ...(truncatedErr !== undefined ? { syncStderr: truncatedErr } : {}),
@@ -285,7 +285,7 @@ async function runKibiCheck(worktree, rules) {
             const truncatedOut = truncateSyncOutput(stdout || undefined);
             const truncatedErr = truncateSyncOutput(stderr || undefined);
             resolve({
-                exitCode: error ? (error.code ?? 1) : 0,
+                exitCode: error && typeof error.code === "number" ? error.code : 0,
                 ...(truncatedOut !== undefined ? { stdout: truncatedOut } : {}),
                 ...(truncatedErr !== undefined ? { stderr: truncatedErr } : {}),
             });

package/dist/session-edit-state.d.ts

@@ -1,4 +1,8 @@
 export type EditEventKind = string;
+export declare function pushEventHintIfKind(hints: Array<{
+    kind: string;
+    timestamp: number;
+}>, kind: string | undefined, timestamp: number): void;
 export interface SessionEditEntry {
     /** Relative file path (relative to worktree root). */
     filePath: string;

package/dist/session-edit-state.js

@@ -1,6 +1,10 @@
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
+export function pushEventHintIfKind(hints, kind, timestamp) {
+    if (kind)
+        hints.push({ kind, timestamp });
+}
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -162,9 +166,7 @@ export function createSessionEditState(opts) {
         const abs = resolveToAbsolute(rel);
         entry.currentHash = hashFile(abs);
         entry.lastReconciledAt = timestamp ?? now();
-        if (kind) {
-            entry.eventHints.push({ kind, timestamp: timestamp ?? now() });
-        }
+        pushEventHintIfKind(entry.eventHints, kind, timestamp ?? now());
     }
     return {
         recordEventHint,

package/dist/smart-enforcement-events.d.ts

@@ -0,0 +1,100 @@
+import type { CommentAnalysisResult } from "./comment-analysis.js";
+import type { FileOperationState } from "./file-operation-state.js";
+import type { CacheKey } from "./guidance-cache.js";
+import type { KbFreshnessScope } from "./kb-freshness-state.js";
+import type { PathKind } from "./path-kind.js";
+import type { RuntimeDegradedOverlay } from "./plugin-startup.js";
+import type { RiskClass } from "./risk-classifier.js";
+import type { SyncScheduler } from "./scheduler.js";
+import type { SessionEditState } from "./session-edit-state.js";
+import type { WarningCategory } from "./session-tracker.js";
+import type { WorkContext } from "./work-context-resolver.js";
+export interface PluginEventInput {
+    sessionId?: string;
+    agentIdentity?: string;
+    worktree: string;
+    directory: string;
+}
+export interface PluginEvent {
+    type: string;
+    properties?: Record<string, unknown>;
+}
+/** Mutable cross-event state shared by the event and chat hooks. */
+export interface SmartEnforcementState {
+    recentEdits: Array<{
+        path: string;
+        kind: PathKind;
+        timestamp: number;
+    }>;
+    hasRecentKbEdit: boolean;
+    recentCommentSuggestion: CommentAnalysisResult | null;
+    seenFingerprints: Set<string>;
+    lastRiskClass: RiskClass | null;
+    lastRiskFilePath: string | null;
+    lastRiskScopeKey: string | null;
+}
+export interface KibiEventEnv {
+    input: PluginEventInput;
+    cfg: {
+        sync: {
+            enabled: boolean;
+        };
+        guidance: {
+            warnOnKbEdits: boolean;
+            commentDetection: {
+                enabled: boolean;
+                minLines: number;
+            };
+            targetedChecks: {
+                enabled: boolean;
+            };
+            smartEnforcement: {
+                degradedMode: string;
+            };
+        };
+    };
+    cache: {
+        isSatisfied(key: CacheKey): boolean;
+    };
+    freshnessStore: {
+        recordToolEvidence(scope: KbFreshnessScope, tool: string): void;
+    };
+    fileFilter: {
+        shouldHandleFile(filePath: string, root: string): boolean;
+    };
+    log: {
+        info(...args: unknown[]): void;
+        warn(...args: unknown[]): void;
+    };
+    rootWorkContext: WorkContext;
+    state: SmartEnforcementState;
+    resolveScopedWorkContext(filePath?: string): WorkContext;
+    getSessionEditState(context: WorkContext): SessionEditState;
+    getFileOperationState(context: WorkContext): FileOperationState;
+    getPathKindCache(context: WorkContext): Map<string, PathKind>;
+    getSchedulerForContext(context: WorkContext): SyncScheduler | null;
+    normalizeSessionPath(filePath: string, worktree?: string): string;
+    resolveWorktreePath(filePath: string, worktree?: string): string;
+    buildRiskPathScopeKey(context: WorkContext, filePath: string): string;
+    buildScopedCacheKey(context: WorkContext, riskClass: RiskClass, fileBucket: string, dirtyRelevantInputs: Iterable<string | null | undefined>): CacheKey;
+    readFileContent(filePath: string, worktree?: string): string;
+    updateRecentEditsFromSession(sessionEdits: Array<{
+        filePath: string;
+        lastReconciledAt: number;
+    }>, scopedPathKindCache: Map<string, PathKind>): SmartEnforcementState["recentEdits"];
+    recordWarning(category: WarningCategory | string, filePath: string, message: string): void;
+    getMaintenanceDegraded(): boolean;
+    getEffectiveMode(): string;
+    posture: {
+        maintenanceDegraded: boolean;
+        state: string;
+    };
+    runtimeOverlay: RuntimeDegradedOverlay;
+    lintRequirementDoc(filePath: string, worktreeRoot: string): Array<{
+        category: string;
+        message: string;
+    }>;
+}
+export declare function isKbToolEventType(eventType: string): boolean;
+export declare function handleKbToolEvent(env: KibiEventEnv, event: PluginEvent, sessionId: string | undefined): void;
+export declare function handleFileLifecycleEvent(env: KibiEventEnv, event: PluginEvent): void;