kibi-cli 0.10.1 → 0.11.1

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAuCA,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AA8CA,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/dist/cli.js

@@ -28,8 +28,10 @@ import { initCommand } from "./commands/init.js";
 import { migrateCommand } from "./commands/migrate.js";
 import { queryCommand } from "./commands/query.js";
 import { searchCommand } from "./commands/search.js";
+import { skillsListCommand, skillsLoadCommand, skillsReadCommand, skillsValidateCommand, } from "./commands/skills.js";
 import { statusCommand } from "./commands/status.js";
 import { syncCommand } from "./commands/sync.js";
+import { usageMetricsCommand } from "./commands/usage-metrics.js";
 const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 const VERSION = packageJson.version ?? "0.1.0";
 // implements REQ-003
@@ -167,6 +169,49 @@ program
     .command("doctor")
     .description("Diagnose KB setup and configuration")
     .action(withExitCode(async () => doctorCommand()));
+program
+    .command("usage-metrics")
+    .description("Report usage and quality metrics from .kb/usage.log")
+    .option("--format <format>", "Output format: json|table", "table")
+    .option("--limit <n>", "Limit top zero-result source files", "10")
+    .action(withExitCode(async (options) => {
+    return usageMetricsCommand(options);
+}));
+const skillsProgram = program
+    .command("skills")
+    .description("Manage bundled markdown skills");
+skillsProgram
+    .command("list")
+    .description("List bundled markdown skills")
+    .option("--format <format>", "Output format: json|table", "table")
+    .action(withExitCode(async (options) => {
+    return skillsListCommand(options);
+}));
+skillsProgram
+    .command("load")
+    .description("Load a bundled markdown skill")
+    .argument("<id>", "Bundled skill ID")
+    .option("--format <format>", "Output format: json|markdown", "markdown")
+    .action(withExitCode(async (id, options) => {
+    return skillsLoadCommand(id, options);
+}));
+skillsProgram
+    .command("read")
+    .description("Read a declared bundled skill resource")
+    .argument("<id>", "Bundled skill ID")
+    .argument("<resource>", "Declared resource path")
+    .option("--format <format>", "Output format: text|json", "text")
+    .action(withExitCode(async (id, resource, options) => {
+    return skillsReadCommand(id, resource, options);
+}));
+skillsProgram
+    .command("validate")
+    .description("Validate a bundled markdown skill path")
+    .argument("<path>", "Skill bundle directory or SKILL.md path")
+    .option("--format <format>", "Output format: json|table", "table")
+    .action(withExitCode(async (pathLike, options) => {
+    return skillsValidateCommand(pathLike, options);
+}));
 program
     .command("branch")
     .description("Manage branch KBs")

package/dist/commands/skills.d.ts

@@ -0,0 +1,14 @@
+import type { CommandResult } from "../cli.js";
+interface FormatOptions<TFormat extends string> {
+    format?: TFormat;
+}
+type ListFormat = "json" | "table";
+type LoadFormat = "json" | "markdown";
+type ReadFormat = "text" | "json";
+type ValidateFormat = "json" | "table";
+export declare function skillsListCommand(options: FormatOptions<ListFormat>): Promise<CommandResult | undefined>;
+export declare function skillsLoadCommand(id: string, options: FormatOptions<LoadFormat>): Promise<CommandResult | undefined>;
+export declare function skillsReadCommand(id: string, resource: string, options: FormatOptions<ReadFormat>): Promise<CommandResult | undefined>;
+export declare function skillsValidateCommand(pathLike: string, options: FormatOptions<ValidateFormat>): Promise<CommandResult | undefined>;
+export {};
+//# sourceMappingURL=skills.d.ts.map

package/dist/commands/skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/commands/skills.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAU/C,UAAU,aAAa,CAAC,OAAO,SAAS,MAAM;IAC5C,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,KAAK,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC;AACnC,KAAK,UAAU,GAAG,MAAM,GAAG,UAAU,CAAC;AACtC,KAAK,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAClC,KAAK,cAAc,GAAG,MAAM,GAAG,OAAO,CAAC;AAGvC,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,aAAa,CAAC,UAAU,CAAC,GACjC,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAUpC;AAED,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,aAAa,CAAC,UAAU,CAAC,GACjC,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAgBpC;AAED,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,aAAa,CAAC,UAAU,CAAC,GACjC,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAUpC;AAED,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,aAAa,CAAC,cAAc,CAAC,GACrC,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAepC"}

package/dist/commands/skills.js

@@ -0,0 +1,86 @@
+import { createHash } from "node:crypto";
+import Table from "cli-table3";
+import { listBundledSkills, loadBundledSkill, readBundledSkillResource, validateSkillBundle, } from "kibi-cli/skills";
+// implements REQ-003
+export async function skillsListCommand(options) {
+    return handleSkillCommand(() => {
+        const skills = listBundledSkills();
+        if (options.format === "json") {
+            console.log(JSON.stringify(skills, null, 2));
+            return;
+        }
+        console.log(renderSkillsTable(skills));
+    });
+}
+export async function skillsLoadCommand(id, options) {
+    return handleSkillCommand(() => {
+        const bundle = loadBundledSkill(id);
+        if (options.format === "json") {
+            console.log(JSON.stringify({
+                metadata: bundle.manifest,
+                body: bundle.body,
+                resources: bundle.manifest.resources ?? [],
+                contentHash: createHash("sha256").update(bundle.body).digest("hex"),
+                sourceType: "bundled",
+            }, null, 2));
+            return;
+        }
+        process.stdout.write(bundle.body.endsWith("\n") ? bundle.body : `${bundle.body}\n`);
+    });
+}
+export async function skillsReadCommand(id, resource, options) {
+    return handleSkillCommand(() => {
+        const contents = readBundledSkillResource(id, resource);
+        if (options.format === "json") {
+            console.log(JSON.stringify({ id, resource, contents }, null, 2));
+            return;
+        }
+        process.stdout.write(contents.endsWith("\n") ? contents : `${contents}\n`);
+    });
+}
+export async function skillsValidateCommand(pathLike, options) {
+    return handleSkillCommand(() => {
+        const result = validateSkillBundle(pathLike);
+        const printable = {
+            valid: result.valid,
+            errors: result.errors.map(formatValidationError),
+        };
+        if (options.format === "json") {
+            console.log(JSON.stringify(printable, null, 2));
+            return;
+        }
+        console.log(renderValidationTable(printable));
+    });
+}
+function handleSkillCommand(action) {
+    try {
+        action();
+        return undefined;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(message);
+        return { exitCode: 1 };
+    }
+}
+function renderSkillsTable(skills) {
+    const table = new Table({ head: ["ID", "Name", "Version", "Description"] });
+    for (const skill of skills) {
+        table.push([skill.id, skill.name, skill.version, skill.description]);
+    }
+    return table.toString();
+}
+function formatValidationError(error) {
+    return { field: error.field, message: error.message };
+}
+function renderValidationTable(result) {
+    const table = new Table({ head: ["Valid", "Field", "Message"] });
+    if (result.errors.length === 0) {
+        table.push([String(result.valid), "", ""]);
+        return table.toString();
+    }
+    for (const error of result.errors) {
+        table.push([String(result.valid), error.field, error.message]);
+    }
+    return table.toString();
+}

package/dist/commands/usage-metrics.d.ts

@@ -0,0 +1,8 @@
+import type { CommandResult } from "../cli.js";
+interface UsageMetricsOptions {
+    format?: "json" | "table";
+    limit?: string;
+}
+export declare function usageMetricsCommand(options: UsageMetricsOptions): Promise<CommandResult | undefined>;
+export {};
+//# sourceMappingURL=usage-metrics.d.ts.map

package/dist/commands/usage-metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-metrics.d.ts","sourceRoot":"","sources":["../../src/commands/usage-metrics.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C,UAAU,mBAAmB;IAC3B,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAkED,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAuBpC"}

package/dist/commands/usage-metrics.js

@@ -0,0 +1,323 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import Table from "cli-table3";
+// implements REQ-003
+export async function usageMetricsCommand(options) {
+    const limit = Number.parseInt(options.limit || "10", 10);
+    if (!Number.isFinite(limit) || limit < 1) {
+        console.error("Error: --limit must be a positive integer");
+        return { exitCode: 1 };
+    }
+    const usageLogPath = path.join(process.cwd(), ".kb", "usage.log");
+    if (!existsSync(usageLogPath)) {
+        console.error(`Error: usage log not found at ${usageLogPath}`);
+        return { exitCode: 1 };
+    }
+    const rows = parseUsageLog(readFileSync(usageLogPath, "utf8"));
+    const report = buildUsageMetricsReport(rows, limit);
+    if (options.format === "json") {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    console.log(renderUsageMetricsReport(report));
+    return;
+}
+function parseUsageLog(contents) {
+    const rows = [];
+    for (const [index, line] of contents.split(/\r?\n/).entries()) {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to parse .kb/usage.log line ${index + 1}: ${message}`);
+        }
+        if (!parsed || typeof parsed !== "object") {
+            throw new Error(`Failed to parse .kb/usage.log line ${index + 1}: expected object`);
+        }
+        rows.push(parsed);
+    }
+    return rows;
+}
+function buildUsageMetricsReport(rows, limit) {
+    const timestamps = rows
+        .map((row) => row.timestamp)
+        .filter((value) => typeof value === "string")
+        .sort((left, right) => left.localeCompare(right));
+    const toolCounts = new Map();
+    const branchCounts = new Map();
+    const zeroResultToolCounts = new Map();
+    const zeroResultSourceFileCounts = new Map();
+    const upsertErrorCategories = new Map();
+    const violationTrend = [];
+    let successCount = 0;
+    let errorCount = 0;
+    let telemetryCompleteCount = 0;
+    let telemetryMissingCount = 0;
+    let zeroResultCount = 0;
+    for (const row of rows) {
+        increment(toolCounts, normalizeKey(row.tool, "unknown"));
+        increment(branchCounts, normalizeKey(row.active_branch || row.branch, "unknown"));
+        const outcome = getOutcome(row);
+        if (outcome === "success") {
+            successCount += 1;
+        }
+        if (outcome === "error") {
+            errorCount += 1;
+        }
+        if (hasCompleteTelemetry(row)) {
+            telemetryCompleteCount += 1;
+        }
+        else {
+            telemetryMissingCount += 1;
+        }
+        if (isZeroResult(row)) {
+            zeroResultCount += 1;
+            increment(zeroResultToolCounts, normalizeKey(row.tool, "unknown"));
+            const sourceFile = getSourceFile(row);
+            if (sourceFile) {
+                increment(zeroResultSourceFileCounts, sourceFile);
+            }
+        }
+        if (row.tool === "kb_check" &&
+            typeof row.violation_count === "number" &&
+            typeof row.timestamp === "string") {
+            violationTrend.push({
+                timestamp: row.timestamp,
+                violationCount: row.violation_count,
+            });
+        }
+        if (row.tool === "kb_upsert" && outcome === "error") {
+            increment(upsertErrorCategories, categorizeUpsertError(row.error_message ?? row.error));
+        }
+    }
+    violationTrend.sort((left, right) => left.timestamp.localeCompare(right.timestamp));
+    return {
+        rowCount: rows.length,
+        dateRange: {
+            first: timestamps[0] ?? null,
+            last: timestamps.at(-1) ?? null,
+        },
+        toolCounts: mapToSortedObject(toolCounts),
+        branchCounts: mapToSortedObject(branchCounts),
+        outcomeCounts: {
+            success: successCount,
+            error: errorCount,
+        },
+        telemetry: {
+            completeCount: telemetryCompleteCount,
+            missingCount: telemetryMissingCount,
+            completenessRate: rows.length === 0 ? 0 : telemetryCompleteCount / rows.length,
+        },
+        zeroResults: {
+            count: zeroResultCount,
+            rate: rows.length === 0 ? 0 : zeroResultCount / rows.length,
+            byTool: mapToSortedObject(zeroResultToolCounts),
+            topSourceFiles: sortCountEntries(zeroResultSourceFileCounts)
+                .slice(0, limit)
+                .map(([sourceFile, count]) => ({ sourceFile, count })),
+        },
+        kbCheck: {
+            violationTrend,
+        },
+        upsertErrors: {
+            categories: mapToSortedObject(upsertErrorCategories),
+        },
+    };
+}
+function hasCompleteTelemetry(row) {
+    if (row.telemetry_status === "provided") {
+        return true;
+    }
+    if (row.telemetry_status === "missing") {
+        return false;
+    }
+    return row.telemetry !== null && row.telemetry !== undefined;
+}
+function getOutcome(row) {
+    if (row.status === "success" || row.status === "error") {
+        return row.status;
+    }
+    if (row.success === true) {
+        return "success";
+    }
+    if (row.success === false) {
+        return "error";
+    }
+    return null;
+}
+function isZeroResult(row) {
+    if (row.zero_results === true) {
+        return true;
+    }
+    if (row.zero_results === false) {
+        return false;
+    }
+    if (row.result_count === 0) {
+        return true;
+    }
+    return row.result_summary === "0 results";
+}
+function getSourceFile(row) {
+    if (typeof row.sourceFile === "string" && row.sourceFile.trim()) {
+        return row.sourceFile;
+    }
+    if (row.args &&
+        typeof row.args.sourceFile === "string" &&
+        row.args.sourceFile.trim()) {
+        return row.args.sourceFile;
+    }
+    if (row.business_args &&
+        typeof row.business_args.sourceFile === "string" &&
+        row.business_args.sourceFile.trim()) {
+        return row.business_args.sourceFile;
+    }
+    return null;
+}
+function categorizeUpsertError(errorMessage) {
+    if (!errorMessage) {
+        return "Unknown error";
+    }
+    if (errorMessage.startsWith("Entity validation failed:")) {
+        return "Entity validation failed";
+    }
+    if (errorMessage.startsWith("Relationship source must match the upserted entity")) {
+        return "Relationship source must match the upserted entity";
+    }
+    const semicolonIndex = errorMessage.indexOf(";");
+    if (semicolonIndex > 0) {
+        return errorMessage.slice(0, semicolonIndex).trim();
+    }
+    const colonIndex = errorMessage.indexOf(":");
+    if (colonIndex > 0) {
+        return errorMessage.slice(0, colonIndex).trim();
+    }
+    return errorMessage.trim() || "Unknown error";
+}
+function increment(counts, key) {
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+}
+function normalizeKey(value, fallback) {
+    return typeof value === "string" && value.trim() ? value : fallback;
+}
+function sortCountEntries(counts) {
+    return [...counts.entries()].sort(([leftKey, leftCount], [rightKey, rightCount]) => rightCount - leftCount || leftKey.localeCompare(rightKey));
+}
+function mapToSortedObject(counts) {
+    return Object.fromEntries(sortCountEntries(counts));
+}
+function renderUsageMetricsReport(report) {
+    const sections = [
+        renderSummaryTable(report),
+        renderCountsTable("Tool Counts", "Tool", report.toolCounts),
+        renderCountsTable("Branch Counts", "Branch", report.branchCounts),
+        renderCountsTable("Outcome Counts", "Outcome", report.outcomeCounts),
+        renderTelemetryTable(report),
+        renderZeroResultsTable(report),
+        renderViolationTrendTable(report),
+        renderCountsTable("Upsert Error Categories", "Category", report.upsertErrors.categories),
+    ].filter(Boolean);
+    return sections.join("\n\n");
+}
+function renderSummaryTable(report) {
+    const table = new Table({
+        head: ["Field", "Value"],
+        colWidths: [24, 56],
+        wordWrap: true,
+    });
+    table.push(["Row Count", String(report.rowCount)], ["First Timestamp", report.dateRange.first ?? "-"], ["Last Timestamp", report.dateRange.last ?? "-"]);
+    return table.toString();
+}
+function renderCountsTable(title, label, counts) {
+    const entries = Object.entries(counts);
+    const table = new Table({
+        head: [label, "Count"],
+        colWidths: [48, 12],
+        wordWrap: true,
+    });
+    if (entries.length === 0) {
+        table.push(["-", "0"]);
+    }
+    else {
+        for (const [key, count] of entries) {
+            table.push([key, String(count)]);
+        }
+    }
+    return `${title}\n${table.toString()}`;
+}
+function renderTelemetryTable(report) {
+    const table = new Table({
+        head: ["Metric", "Value"],
+        colWidths: [32, 28],
+        wordWrap: true,
+    });
+    table.push(["Complete", String(report.telemetry.completeCount)], ["Missing", String(report.telemetry.missingCount)], ["Completeness Rate", formatRate(report.telemetry.completenessRate)]);
+    return `Telemetry\n${table.toString()}`;
+}
+function renderZeroResultsTable(report) {
+    const summary = new Table({
+        head: ["Metric", "Value"],
+        colWidths: [32, 28],
+        wordWrap: true,
+    });
+    summary.push(["Count", String(report.zeroResults.count)], ["Rate", formatRate(report.zeroResults.rate)]);
+    const byTool = new Table({
+        head: ["Tool", "Count"],
+        colWidths: [48, 12],
+        wordWrap: true,
+    });
+    const byToolEntries = Object.entries(report.zeroResults.byTool);
+    if (byToolEntries.length === 0) {
+        byTool.push(["-", "0"]);
+    }
+    else {
+        for (const [tool, count] of byToolEntries) {
+            byTool.push([tool, String(count)]);
+        }
+    }
+    const sourceFiles = new Table({
+        head: ["Source File", "Zero Results"],
+        colWidths: [48, 14],
+        wordWrap: true,
+    });
+    if (report.zeroResults.topSourceFiles.length === 0) {
+        sourceFiles.push(["-", "0"]);
+    }
+    else {
+        for (const entry of report.zeroResults.topSourceFiles) {
+            sourceFiles.push([entry.sourceFile, String(entry.count)]);
+        }
+    }
+    return [
+        "Zero Results",
+        summary.toString(),
+        "Zero-Result Counts By Tool",
+        byTool.toString(),
+        "Zero-Result Source Files",
+        sourceFiles.toString(),
+    ].join("\n");
+}
+function renderViolationTrendTable(report) {
+    const table = new Table({
+        head: ["Timestamp", "Violations"],
+        colWidths: [32, 12],
+        wordWrap: true,
+    });
+    if (report.kbCheck.violationTrend.length === 0) {
+        table.push(["-", "0"]);
+    }
+    else {
+        for (const entry of report.kbCheck.violationTrend) {
+            table.push([entry.timestamp, String(entry.violationCount)]);
+        }
+    }
+    return `KB Check Violation Trend\n${table.toString()}`;
+}
+function formatRate(value) {
+    return `${(value * 100).toFixed(1)}%`;
+}

package/dist/public/skills/kibi-usage/SKILL.md

@@ -0,0 +1,125 @@
+---
+id: kibi-usage
+name: Kibi Usage
+description: Guides agents to use Kibi MCP, facts, relationships, and validation correctly
+version: 1.0.0
+kibiCompatibility: ">=0.11.0"
+tags:
+  - kibi
+  - mcp
+  - knowledge-base
+  - traceability
+  - agent-guidance
+resources:
+  - resources/relationship-directions.md
+  - resources/fact-lanes.md
+  - resources/workflows.md
+---
+
+# Kibi Usage
+
+Consult this skill before any Kibi knowledge base operation, on first interaction with a Kibi-enabled repo, after detecting stale or dirty KB status, and before performing mutations.
+
+## MCP-Only Rules
+
+Interact with the knowledge base exclusively through MCP tools. Do not read or edit files inside `.kb/` directly. Do not run any `kibi` CLI commands from the agent session. The MCP surface is the only sanctioned interface for agents.
+
+## Discovery-First Workflow
+
+Always discover before you mutate. Start with `kb_search` for exploratory discovery across metadata and markdown body text. Split broad queries into 1-3 focused probes. Review top hits for relevance before concluding the KB lacks knowledge.
+
+Follow up with `kb_query` for exact lookups by `id`, `type`, `tags`, or `sourceFile`. Call `kb_status` to inspect branch attachment and freshness when stale context would affect decisions. Only after discovery and confirmation should you mutate.
+
+## Relationship Directions
+
+Relationship direction is fixed and semantic. Getting it wrong breaks traceability queries and validation.
+
+| Relationship | Direction | Meaning |
+|-------------|-----------|---------|
+| `implements` | symbol -> req | Symbol owns or implements requirement behavior |
+| `specified_by` | req -> scenario | Requirement is specified by a scenario |
+| `verified_by` | req/scenario -> test | Requirement or scenario is verified by a test |
+| `validates` | test -> req/scenario | Test validates a requirement or scenario |
+| `executable_for` | symbol -> test | Symbol is executable test code for a test entity |
+| `constrains` | req -> fact(subject) | Requirement constrains a domain fact |
+| `requires_property` | req -> fact(property_value) | Requirement requires a property value |
+| `supersedes` | old-req -> new-req | Old requirement is replaced by new requirement |
+| `covered_by` | symbol -> test | Production symbol has coverage evidence from a test |
+
+See `resources/relationship-directions.md` for detailed payload examples.
+
+## Strict Fact Lane
+
+Normative requirements that must participate in contradiction blocking use the strict fact lane. Create a `fact_kind: subject` fact and link it from the requirement via `constrains`. Create a `fact_kind: property_value` fact and link it via `requires_property`.
+
+```yaml
+# Fact entity
+id: FACT-USER-ROLE
+title: User Role Assignment
+status: active
+fact_kind: subject
+subject_key: user.role_assignment
+
+# Requirement entity
+id: REQ-019
+title: Users can have up to 3 roles
+status: open
+relationships:
+  - type: constrains
+    from: REQ-019
+    to: FACT-USER-ROLE
+  - type: requires_property
+    from: REQ-019
+    to: FACT-LIMIT-3
+```
+
+See `resources/fact-lanes.md` for the full strict vs observation lane comparison.
+
+## Fact vs Flag
+
+Use `flag` for runtime or config gates only. Feature flags, kill-switches, and deferred capabilities are valid `flag` entities.
+
+Bugs, incidents, and workarounds belong in `fact` entities with `fact_kind: observation` or `meta`. These fact kinds are excluded from contradiction inference, making them appropriate for non-blocking evidence.
+
+Anti-example: do not create a `flag` named `BUG-123` to track a defect. Create a `fact` with `fact_kind: observation` instead.
+
+## Create-Before-Link
+
+Always confirm or create endpoint entities before linking them. Query target IDs with `kb_query` first. If an endpoint does not exist, create it with `kb_upsert` before creating the relationship. Creating relationships to non-existent entities produces dangling references that `kb_check` will flag.
+
+## Sequential Upserts
+
+Never fire `kb_upsert` calls in parallel. Execute them sequentially to avoid lock contention and ensure deterministic ordering. This is especially important when creating chains of related entities.
+
+## Targeted and Final Checks
+
+Run `kb_check` with specific rules during iteration for fast feedback. For example, use `rules: ["required-fields", "no-dangling-refs"]` after small changes. Run a full `kb_check` without rule filters before declaring work complete.
+
+## Domain Contradictions and Evolution
+
+The `domain-contradictions` rule detects conflicts between strict-lane facts linked to requirements. When a contradiction is found, the supported escape hatch is `supersedes`: create a new requirement that supersedes the old one, then link the new requirement to updated facts.
+
+Use `kb_model_requirement` for automated strict-fact modeling. It generates the subject and property_value facts, links them via `constrains` and `requires_property`, and handles low-confidence downgrades to `observation` facts automatically.
+
+## Stale or Dirty KB Handling
+
+Call `kb_status` when you suspect the branch KB is stale or when switching context. Report freshness findings to the user rather than relying on outdated KB context. If `kb_status` indicates a schema migration is needed, ask the user or operator to handle it outside the agent session.
+
+## Anti-Patterns and Remediation
+
+| Anti-Pattern | Problem | Remediation |
+|-------------|---------|-------------|
+| Reversed relationship direction | Traceability queries break | Verify direction against the relationship table above |
+| Bug-as-flag | `flag` misused for defect tracking | Use `fact` with `fact_kind: observation` or `meta` |
+| Parallel upserts | Lock contention and nondeterminism | Execute `kb_upsert` calls sequentially |
+| Embedded scenarios in reqs | Violates canonical traceability chain | Create separate `req`, `scen`, and `test` entities |
+| Missing `kb_check` | Undetected dangling refs and violations | Run targeted checks during work, full check at completion |
+| Tags as multi-ID lookup | Tags are metadata, not identifiers | Use `kb_query` with explicit `id` values |
+| `relates_to` for strict modeling | Loses contradiction safety | Use `constrains` and `requires_property` instead |
+
+Before/after for reversed direction:
+
+- Wrong: `relationships: [{ type: "implements", from: "REQ-001", to: "SYM-001" }]`
+- Right: `relationships: [{ type: "implements", from: "SYM-001", to: "REQ-001" }]`
+
+See `resources/workflows.md` for the golden-path discovery to validation sequence.

package/dist/public/skills/kibi-usage/resources/fact-lanes.md

@@ -0,0 +1,45 @@
+# Fact Lanes
+
+## Strict Lane (Contradiction-Safe)
+
+### fact_kind: subject
+```yaml
+id: FACT-USER-ROLE
+title: User Role Assignment
+status: active
+fact_kind: subject
+subject_key: user.role_assignment
+```
+
+### fact_kind: property_value
+```yaml
+id: FACT-LIMIT-3
+title: Maximum of Three Roles
+status: active
+fact_kind: property_value
+subject_key: user.role_assignment
+property_key: max_roles
+operator: lte
+value_type: int
+value_int: 3
+```
+
+## Context Lane (Non-Blocking)
+
+### fact_kind: observation
+For bug records, incident notes, and observed behavior.
+```yaml
+id: FACT-BUG-123
+title: Login fails on Safari 17
+status: active
+fact_kind: observation
+```
+
+### fact_kind: meta
+For governance notes, process commentary, and workaround documentation.
+```yaml
+id: FACT-WORKAROUND-456
+title: Temporary cache bypass for v2 migration
+status: active
+fact_kind: meta
+```