kibi-cli 0.17.0 → 0.18.1

package/dist/traceability/temp-kb.js

@@ -133,7 +133,7 @@ function serializeTypedFactFields(entity) {
     }
     return fields;
 }
-function buildEntityAssertionGoal(entity) {
+function buildEntityAssertionGoal(entity, sourceFile) {
     const props = [
         `id=${toPrologAtom(entity.id)}`,
         `title=${toPrologString(entity.title)}`,
@@ -153,12 +153,45 @@ function buildEntityAssertionGoal(entity) {
         props.push(`severity=${toPrologAtom(entity.severity)}`);
     if (entity.text_ref)
         props.push(`text_ref=${toPrologString(entity.text_ref)}`);
+    if (entity.type === "req" && entity.semantic_text) {
+        props.push(`semantic_text=${toPrologString(entity.semantic_text)}`);
+    }
     if (entity.type === "req" && entity.logic_claims) {
         props.push(`logic_claims=[${entity.logic_claims.map(toPrologAtom).join(",")}]`);
     }
+    if (entity.type === "req" && entity.semantic_clauses) {
+        props.push(`semantic_clauses=[${entity.semantic_clauses.map(toPrologString).join(",")}]`);
+    }
+    if (entity.type === "req" && entity.semantic_inventory_version) {
+        props.push(`semantic_inventory_version=${toPrologString(entity.semantic_inventory_version)}`);
+    }
+    if (entity.type === "req" && entity.semantic_source_field) {
+        props.push(`semantic_source_field=${toPrologString(entity.semantic_source_field)}`);
+    }
+    if (entity.type === "req" && entity.semantic_source_hash) {
+        props.push(`semantic_source_hash=${toPrologString(entity.semantic_source_hash)}`);
+    }
     if (entity.type === "req" && entity.semantic_inventory) {
         props.push(`semantic_inventory=${toPrologString(JSON.stringify(entity.semantic_inventory))}`);
     }
+    if (sourceFile)
+        props.push(`sourceFile=${toPrologString(sourceFile)}`);
+    if (entity.type === "symbol") {
+        if (entity.symbol_role)
+            props.push(`symbol_role=${toPrologAtom(entity.symbol_role)}`);
+        if (entity.granularity_reason)
+            props.push(`granularity_reason=${toPrologAtom(entity.granularity_reason)}`);
+        for (const key of [
+            "sourceLine",
+            "sourceColumn",
+            "sourceEndLine",
+            "sourceEndColumn",
+        ]) {
+            const value = entity[key];
+            if (typeof value === "number")
+                props.push(`${key}=${value}`);
+        }
+    }
     if (entity.type === "fact") {
         props.push(...serializeTypedFactFields(entity));
     }
@@ -215,11 +248,11 @@ async function consultOverlay(ctx) {
 export { consultOverlay };
 // implements REQ-014
 export async function projectStagedEntities(prolog, results) {
-    for (const { entity } of results) {
+    for (const { entity, sourceFile } of results) {
         // Retract stale relationships before re-asserting entity
         // (kb_assert_entity_no_audit preserves relationships on upsert)
         await prolog.query(`kb_retract_entity_relationships('${entity.id}')`);
-        const assertEntityResult = await prolog.query(buildEntityAssertionGoal(entity));
+        const assertEntityResult = await prolog.query(buildEntityAssertionGoal(entity, sourceFile));
         if (!assertEntityResult.success) {
             throw new Error(`Failed to assert staged entity ${entity.id}: ${assertEntityResult.error || "unknown error"}`);
         }

package/dist/types/entities.d.ts

@@ -47,6 +47,7 @@ export interface TestVerificationFields {
 }
 export type Requirement = BaseEntity & {
     type: "req";
+    semantic_text?: string;
     logic_claims?: string[];
 };
 export type Scenario = BaseEntity & {

package/dist/types/entities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entities.d.ts","sourceRoot":"","sources":["../../src/types/entities.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"entities.d.ts","sourceRoot":"","sources":["../../src/types/entities.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAGD,MAAM,WAAW,UAAU;IACzB,SAAS,CAAC,EACN,SAAS,GACT,gBAAgB,GAChB,aAAa,GACb,MAAM,GACN,kBAAkB,GAClB,WAAW,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,CAAC;IACtD,UAAU,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAClD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;IACpD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,sBAAsB;IACrC,kBAAkB,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,YAAY,CAAC;IAC3D,wBAAwB,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;CACpD;AAED,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG;IACrC,IAAI,EAAE,KAAK,CAAC;IACZ,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB,CAAC;AACF,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC;AACzD,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,sBAAsB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAChF,MAAM,MAAM,GAAG,GAAG,UAAU,GAAG;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC;AAC/C,MAAM,MAAM,IAAI,GAAG,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AACjD,MAAM,MAAM,KAAK,GAAG,UAAU,GAAG;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AACnD,MAAM,MAAM,MAAM,GAAG,UAAU,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AACrD,MAAM,MAAM,IAAI,GAAG,UAAU,GAAG,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9D,MAAM,MAAM,MAAM,GACd,WAAW,GACX,QAAQ,GACR,UAAU,GACV,GAAG,GACH,IAAI,GACJ,KAAK,GACL,MAAM,GACN,IAAI,CAAC"}

package/dist/utils/rule-registry.d.ts

@@ -18,6 +18,8 @@ export interface Violation {
     description: string;
     suggestion?: string;
     source?: string;
+    /** Exact source-bound proof evidence, when the check can produce it. */
+    evidence?: Readonly<Record<string, unknown>>;
 }
 export interface ChecksConfig {
     rules: Record<string, boolean>;

package/dist/utils/rule-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rule-registry.d.ts","sourceRoot":"","sources":["../../src/utils/rule-registry.ts"],"names":[],"mappings":"AAkBA;;;GAGG;AAEH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,OAAO,CAAC;IACxB,QAAQ,EAAE,UAAU,GAAG,WAAW,GAAG,WAAW,GAAG,cAAc,CAAC;CACnE;AAED,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,mCAAmC;AACnC,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,kBAAkB,EAAE,yBAAyB,CAAC;CAC/C;AAED;;;GAGG;AACH,eAAO,MAAM,KAAK,EAAE,SAAS,cAAc,EAsHjC,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,UAAU,aAAoC,CAAC;AAE5D;;GAEG;AACH,eAAO,MAAM,qBAAqB,EAAE,YAKnC,CAAC;AAEF;;;;;GAKG;AAEH,wBAAgB,iBAAiB,CAC/B,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,QAAQ,CAAC,EAAE,MAAM,GAChB,GAAG,CAAC,MAAM,CAAC,CAsBb;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK5D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC9B,YAAY,CAWd"}
+{"version":3,"file":"rule-registry.d.ts","sourceRoot":"","sources":["../../src/utils/rule-registry.ts"],"names":[],"mappings":"AAkBA;;;GAGG;AAEH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,OAAO,CAAC;IACxB,QAAQ,EAAE,UAAU,GAAG,WAAW,GAAG,WAAW,GAAG,cAAc,CAAC;CACnE;AAED,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,mCAAmC;AACnC,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,kBAAkB,EAAE,yBAAyB,CAAC;CAC/C;AAED;;;GAGG;AACH,eAAO,MAAM,KAAK,EAAE,SAAS,cAAc,EAsHjC,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,UAAU,aAAoC,CAAC;AAE5D;;GAEG;AACH,eAAO,MAAM,qBAAqB,EAAE,YAKnC,CAAC;AAEF;;;;;GAKG;AAEH,wBAAgB,iBAAiB,CAC/B,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,QAAQ,CAAC,EAAE,MAAM,GAChB,GAAG,CAAC,MAAM,CAAC,CAsBb;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK5D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC9B,YAAY,CAWd"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cli",
-  "version": "0.17.0",
+  "version": "0.18.1",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {
@@ -34,6 +34,14 @@
       "types": "./dist/public/operations/runtime-types.d.ts",
       "default": "./dist/public/operations/runtime-types.js"
     },
+    "./operations/node-ports": {
+      "types": "./dist/public/operations/node-ports.d.ts",
+      "default": "./dist/public/operations/node-ports.js"
+    },
+    "./verification-receipt": {
+      "types": "./dist/public/verification-receipt.d.ts",
+      "default": "./dist/public/verification-receipt.js"
+    },
     "./operations/semantic-advisor/analyze-prose": {
       "types": "./dist/operations/semantic-advisor/analyze-prose.d.ts",
       "default": "./dist/operations/semantic-advisor/analyze-prose.js"
@@ -90,6 +98,26 @@
       "types": "./dist/public/impact-diagnostics.d.ts",
       "default": "./dist/public/impact-diagnostics.js"
     },
+    "./telemetry-acceptance": {
+      "types": "./dist/public/telemetry-acceptance.d.ts",
+      "default": "./dist/public/telemetry-acceptance.js"
+    },
+    "./telemetry-remediation": {
+      "types": "./dist/public/telemetry-remediation.d.ts",
+      "default": "./dist/public/telemetry-remediation.js"
+    },
+    "./diagnostic-usage": {
+      "types": "./dist/public/diagnostic-usage.d.ts",
+      "default": "./dist/public/diagnostic-usage.js"
+    },
+    "./distribution-parity": {
+      "types": "./dist/public/distribution-parity.d.ts",
+      "default": "./dist/public/distribution-parity.js"
+    },
+    "./legacy-migration-plan": {
+      "types": "./dist/public/operations/legacy-migration-plan.d.ts",
+      "default": "./dist/public/operations/legacy-migration-plan.js"
+    },
     "./public/symbol-granularity": {
       "types": "./dist/public/symbol-granularity.d.ts",
       "default": "./dist/public/symbol-granularity.js"
@@ -161,7 +189,7 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-core": "^0.8.0",
+    "kibi-core": "^0.9.1",
     "ts-morph": "^23.0.0",
     "ignore": "^5.3.0"
   },

package/src/public/diagnostic-usage.ts

@@ -0,0 +1,206 @@
+import { createHash, randomUUID } from "node:crypto";
+import { appendFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+
+export interface DiagnosticUsageInput {
+  readonly workspaceRoot: string;
+  readonly tool: string;
+  readonly businessArgs: Readonly<Record<string, unknown>>;
+  readonly telemetry: Readonly<Record<string, unknown>> | null;
+  readonly startedAt: Date;
+  readonly finishedAt?: Date;
+  readonly status: "success" | "error";
+  readonly result?: unknown;
+  readonly error?: string;
+  readonly requestId?: string;
+  readonly logPath?: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function resultRecord(result: unknown): Record<string, unknown> | undefined {
+  if (!isRecord(result)) return undefined;
+  return isRecord(result.structuredContent) ? result.structuredContent : result;
+}
+
+function stringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === "string")
+    : [];
+}
+
+function canonicalValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalValue);
+  if (!isRecord(value)) return value;
+  return Object.fromEntries(
+    Object.entries(value)
+      .filter(([key]) => key !== "_diagnostic_telemetry")
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, child]) => [key, canonicalValue(child)]),
+  );
+}
+
+export function diagnosticMutationFingerprint(
+  args: Readonly<Record<string, unknown>>,
+): string {
+  return createHash("sha256")
+    .update(JSON.stringify(canonicalValue(args)))
+    .digest("hex");
+}
+
+function appendMutationFields(
+  fields: Record<string, unknown>,
+  args: Readonly<Record<string, unknown>>,
+): void {
+  fields.mutation_fingerprint = diagnosticMutationFingerprint(args);
+  const type = typeof args.type === "string" ? args.type : "unknown";
+  const id = typeof args.id === "string" ? args.id : "unknown";
+  fields.mutation_target = `${type}:${id}`;
+}
+
+function appendSemanticFields(
+  fields: Record<string, unknown>,
+  receipt: unknown,
+): void {
+  if (!isRecord(receipt)) return;
+  const inventory = isRecord(receipt.inventory_contract)
+    ? receipt.inventory_contract
+    : undefined;
+  if (typeof inventory?.source_hash === "string") {
+    fields.semantic_source_hash = inventory.source_hash;
+  }
+  if (typeof receipt.logic_readiness === "string") {
+    fields.semantic_logic_readiness = receipt.logic_readiness;
+  }
+  if (typeof receipt.candidate_lane === "string") {
+    fields.semantic_candidate_lane = receipt.candidate_lane;
+  }
+}
+
+const RECEIPT_GAP_CODES = new Set([
+  "missing_verification_receipt",
+  "stale_verification_receipt",
+  "failed_verification_receipt",
+  "invalid_verification_receipt",
+  "verification_snapshot_unavailable",
+]);
+
+function appendCoverageFields(
+  fields: Record<string, unknown>,
+  args: Readonly<Record<string, unknown>>,
+  result: Record<string, unknown>,
+): void {
+  const rows = Array.isArray(result.rows) ? result.rows.filter(isRecord) : [];
+  const summary = isRecord(result.summary) ? result.summary : {};
+  const gapCodes = rows.flatMap((row) => stringArray(row.proofGaps));
+  const repairPlan = isRecord(result.repairPlan)
+    ? result.repairPlan
+    : undefined;
+  const scope = isRecord(repairPlan?.scope) ? repairPlan.scope : undefined;
+  fields.coverage_by = typeof args.by === "string" ? args.by : "req";
+  fields.coverage_requirement_count = Number(summary.total ?? rows.length);
+  fields.coverage_proven_count = Number(summary.proofProven ?? 0);
+  fields.coverage_proof_missing_count = Number(summary.proofMissing ?? 0);
+  fields.coverage_proof_gap_count = gapCodes.length;
+  fields.coverage_gap_codes = [...new Set(gapCodes)].sort();
+  fields.coverage_receipt_gap_count = gapCodes.filter((code) =>
+    RECEIPT_GAP_CODES.has(code),
+  ).length;
+  if (typeof scope?.complete === "boolean") {
+    fields.coverage_scope_complete = scope.complete;
+  }
+}
+
+export function deriveDiagnosticUsageFields(
+  tool: string,
+  args: Readonly<Record<string, unknown>>,
+  telemetry: Readonly<Record<string, unknown>> | null,
+  result: unknown,
+): Record<string, unknown> {
+  const fields: Record<string, unknown> = {
+    telemetry_status: telemetry ? "provided" : "missing",
+  };
+  if (telemetry) {
+    fields.telemetry_is_autonomous = telemetry.is_autonomous ?? null;
+    fields.telemetry_confidence_score = telemetry.confidence_score ?? null;
+    fields.telemetry_attempt_number = telemetry.attempt_number ?? null;
+    if (typeof telemetry.session_id === "string") {
+      fields.session_id = telemetry.session_id;
+    }
+    if (typeof telemetry.actor_id === "string") {
+      fields.actor_id = telemetry.actor_id;
+    }
+  }
+
+  const structured = resultRecord(result);
+  if (tool === "kb_query" || tool === "kb_search") {
+    const resultCount = Number(structured?.count ?? 0);
+    fields.result_count = resultCount;
+    fields.zero_results = resultCount === 0;
+    fields.result_summary =
+      resultCount === 0 ? "0 results" : `${resultCount} results`;
+  }
+  if (tool === "kb_check") {
+    const count = Number(structured?.count ?? 0);
+    fields.violation_count = count;
+    fields.requested_rules = Array.isArray(args.rules) ? args.rules : [];
+    fields.result_summary =
+      count === 0 ? "0 violations" : `${count} violations`;
+  }
+  if (tool === "kb_coverage" && structured) {
+    appendCoverageFields(fields, args, structured);
+    fields.result_summary = `${String(
+      fields.coverage_proven_count,
+    )} proven; ${String(fields.coverage_proof_gap_count)} proof gaps`;
+  }
+  if (tool === "kb_semantic_advisor" && structured) {
+    appendSemanticFields(fields, structured.receipt);
+  }
+  if (tool === "kb_validate_upsert") {
+    appendMutationFields(fields, args);
+    fields.validation_valid = structured?.valid === true;
+    appendSemanticFields(fields, structured?.semanticAdvisor);
+  }
+  if (tool === "kb_upsert") {
+    appendMutationFields(fields, args);
+    appendSemanticFields(fields, structured?.semanticAdvisor);
+  }
+  if (!fields.result_summary) fields.result_summary = `${tool} completed`;
+  return fields;
+}
+
+export function appendCliDiagnosticUsage(input: DiagnosticUsageInput): void {
+  const finishedAt = input.finishedAt ?? new Date();
+  const requestId = input.requestId ?? `cli-${randomUUID()}`;
+  const logPath =
+    input.logPath ??
+    process.env.KIBI_CLI_DIAGNOSTIC_USAGE_LOG_PATH ??
+    path.join(input.workspaceRoot, ".kb", "usage.log");
+  mkdirSync(path.dirname(logPath), { recursive: true });
+  appendFileSync(
+    logPath,
+    `${JSON.stringify({
+      timestamp: finishedAt.toISOString(),
+      request_id: requestId,
+      tool: input.tool,
+      interface: "cli_json",
+      telemetry: input.telemetry,
+      business_args: input.businessArgs,
+      status: input.status,
+      started_at: input.startedAt.toISOString(),
+      finished_at: finishedAt.toISOString(),
+      duration_ms: finishedAt.getTime() - input.startedAt.getTime(),
+      active_branch: process.env.KIBI_BRANCH ?? null,
+      ...(input.error ? { error_message: input.error } : {}),
+      ...deriveDiagnosticUsageFields(
+        input.tool,
+        input.businessArgs,
+        input.telemetry,
+        input.result,
+      ),
+    })}\n`,
+    "utf8",
+  );
+}