kibi-cli 2.3.0 → 2.5.0

package/dist/utils/rule-registry.generated.js

@@ -38,6 +38,12 @@ export const GENERATED_RULES = [
         enforcementClass: "canonical",
         category: "integrity",
     },
+    {
+        name: "source-path-dangling",
+        description: "An authored entity's source field must name an existing workspace path (a #anchor suffix is ignored), an existing entity id, or an http(s) URL; a missing source is allowed",
+        enforcementClass: "canonical",
+        category: "integrity",
+    },
     {
         name: "no-cycles",
         description: "No circular dependency chains in requirements",
@@ -56,6 +62,42 @@ export const GENERATED_RULES = [
         enforcementClass: "canonical",
         category: "lifecycle",
     },
+    {
+        name: "superseded-requirement-open",
+        description: "A requirement that another requirement supersedes must have status closed, and supersedes links between requirements must not form a cycle",
+        enforcementClass: "canonical",
+        category: "lifecycle",
+    },
+    {
+        name: "scenario-feasibility",
+        description: "A scenario that expects success must not assume property values that cannot hold, alone or together, with what current requirements require through typed property values or rules, unless an approved exception requirement waives that requirement or the listed clauses",
+        enforcementClass: "canonical",
+        category: "integrity",
+    },
+    {
+        name: "scenario-feasibility-unknown",
+        description: "Advisory: a scenario that expects success assumes nothing, assumes values that contradict each other, assumes a property value no governing requirement constrains comparably (type, unit or operator mismatch, or conflicting requirements), leaves a governing rule's conditions undecided, or conflicts only with constraints whose validity window may not cover it, so its feasibility cannot be decided",
+        enforcementClass: "advisory",
+        category: "integrity",
+    },
+    {
+        name: "exception-claim-keys",
+        description: "An exception requirement's exempts_claims must name claim keys of a requirement it exempts, and requires an exempts link",
+        enforcementClass: "canonical",
+        category: "integrity",
+    },
+    {
+        name: "numeric-string-value",
+        description: "Advisory: a property value stores a numeric-looking string where the comparison is numeric (ordering operator, or an int/number fact on the same property); the finding names the fact and the typed value, without converting it",
+        enforcementClass: "advisory",
+        category: "integrity",
+    },
+    {
+        name: "rule-key-arguments-missing",
+        description: "Advisory: an opposing rule pair stays unresolved only because a body predicate declares no key_arguments; the finding names the predicate and the key positions that would decide the pair",
+        enforcementClass: "advisory",
+        category: "integrity",
+    },
     {
         name: "domain-contradictions",
         description: "Detect contradictions between requirements constraining the same fact",
@@ -95,7 +137,7 @@ export const GENERATED_RULES = [
     {
         name: "strict-fact-shape",
         description: "Detect malformed strict facts (facts with fact_kind that are missing required fields)",
-        enforcementClass: "advisory",
+        enforcementClass: "canonical",
         category: "integrity",
     },
     {
@@ -149,13 +191,13 @@ export const GENERATED_RULES = [
     },
     {
         name: "subject-key-identity",
-        description: "Subject keys must name a shared component, not be derived from a requirement ID",
+        description: "Subject keys must name a shared component, not be derived from a requirement ID, and one subject or claim must not be minted as several active subject facts or identical property_value facts",
         enforcementClass: "advisory",
         category: "integrity",
     },
     {
         name: "subject-key-shape",
-        description: "Subject keys follow dotted component.aspect[.sub] with lowercase snake segments",
+        description: "Subject keys follow dotted component.aspect[.sub] with lowercase snake segments, and property keys name a property rather than a numbered clause (clause_NN)",
         enforcementClass: "advisory",
         category: "integrity",
     },
@@ -166,6 +208,50 @@ export const GENERATED_RULES = [
         category: "integrity",
         diagnosticSeverity: "info",
     },
+    {
+        name: "exception-unapproved",
+        description: "Advisory: a current exception requirement exempts another requirement but has no approved_by, so it exempts nothing until a human approves it",
+        enforcementClass: "advisory",
+        category: "integrity",
+    },
+    {
+        name: "exception-approval-self-attested",
+        description: "Advisory: an agent-authored exception records approved_by but no human corroborated it (origin.approved_by or approval_ref is missing), so a human should confirm the approval",
+        enforcementClass: "advisory",
+        category: "integrity",
+    },
+    {
+        name: "agent-requirement-unapproved",
+        description: "Informational: current requirements authored by an agent (origin.kind agent) that no human has approved (origin.approved_by), listed up to 25 per check",
+        enforcementClass: "advisory",
+        category: "lifecycle",
+        diagnosticSeverity: "info",
+    },
+    {
+        name: "requirement-rationale-missing",
+        description: "Advisory: a current requirement authored by a human or an agent (origin.kind human or agent) states no rationale: no rationale field, no Rationale or Why section in its body, and no link to an ADR; listed up to 25 per check plus one summary finding",
+        enforcementClass: "advisory",
+        category: "lifecycle",
+    },
+    {
+        name: "symbol-owner-superseded",
+        description: "Advisory: a symbol whose every implements target is superseded or deprecated has no current owning requirement; listed up to 25 per check plus one summary finding",
+        enforcementClass: "advisory",
+        category: "traceability",
+    },
+    {
+        name: "adr-unlinked",
+        description: "Advisory: an accepted ADR that no requirement or other ADR is linked with (relates_to, supersedes or any typed edge, in either direction)",
+        enforcementClass: "advisory",
+        category: "lifecycle",
+    },
+    {
+        name: "adr-proposed",
+        description: "Informational: an ADR that is still proposed and not superseded, so nobody accepted or withdrew the decision",
+        enforcementClass: "advisory",
+        category: "lifecycle",
+        diagnosticSeverity: "info",
+    },
     {
         name: "predicate-schema-conformance",
         description: "Predicate facts match a predicate_schema (project-local, or the built-in catalog in the default namespace) and use its declared argument constants",

package/dist/utils/schema-version.d.ts

@@ -1,4 +1,4 @@
-export declare const LATEST_KB_SCHEMA_VERSION = 5;
+export declare const LATEST_KB_SCHEMA_VERSION = 7;
 export interface SchemaVersionStatus {
     status: "missing" | "invalid" | "older" | "current" | "newer";
     currentVersion: number | null;

package/dist/utils/schema-version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-version.d.ts","sourceRoot":"","sources":["../../src/utils/schema-version.ts"],"names":[],"mappings":"AAmBA,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC;IAC9D,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;CAAE,GACrD,IAAI,GACJ,SAAS,CAAC;AAGd,wBAAgB,sBAAsB,CACpC,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAChD,MAAM,GAAG,IAAI,CAgBf;AAGD,wBAAgB,sBAAsB,CACpC,MAAM,CAAC,EAAE,mBAAmB,GAC3B,mBAAmB,CAgDrB"}
+{"version":3,"file":"schema-version.d.ts","sourceRoot":"","sources":["../../src/utils/schema-version.ts"],"names":[],"mappings":"AAoBA,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC;IAC9D,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;CAAE,GACrD,IAAI,GACJ,SAAS,CAAC;AAGd,wBAAgB,sBAAsB,CACpC,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAChD,MAAM,GAAG,IAAI,CAgBf;AAGD,wBAAgB,sBAAsB,CACpC,MAAM,CAAC,EAAE,mBAAmB,GAC3B,mBAAmB,CAgDrB"}

package/dist/utils/schema-version.js

@@ -16,7 +16,8 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 // implements REQ-003
-export const LATEST_KB_SCHEMA_VERSION = 5;
+// Schema 7 requires strict fact shapes and encodes legacy polarity values.
+export const LATEST_KB_SCHEMA_VERSION = 7;
 // implements REQ-003
 export function normalizeSchemaVersion(schemaVersion) {
     if (schemaVersion === undefined || schemaVersion === null) {
@@ -47,7 +48,7 @@ export function getSchemaVersionStatus(config) {
             latestVersion,
             needsMigration: true,
             warning: hasSchemaVersion
-                ? "KB schemaVersion is invalid and should be migrated."
+                ? "KB schemaVersion is invalid; run 'kibi migrate' to plan the repair."
                 : "KB schemaVersion is missing; the repository should be initialized or migrated.",
         };
     }
@@ -66,7 +67,7 @@ export function getSchemaVersionStatus(config) {
             currentVersion,
             latestVersion,
             needsMigration: true,
-            warning: `KB schemaVersion ${currentVersion} is older than the latest version ${latestVersion} and should be migrated.`,
+            warning: `KB schemaVersion ${currentVersion} is older than the latest version ${latestVersion}; run 'kibi migrate' to plan the upgrade.`,
         };
     }
     return {

package/dist/utils/strict-modeling.d.ts

@@ -4,7 +4,7 @@ export interface SemanticClaim {
     source: string;
     subjectKey: string;
     propertyKey: string;
-    operator: "eq" | "gte" | "lte" | "neq" | "bool" | "polarity";
+    operator: "eq" | "gt" | "gte" | "lt" | "lte" | "neq" | "bool" | "polarity";
     value: string | number | boolean;
     confidence: number;
     provenance?: string;

package/dist/utils/strict-modeling.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"strict-modeling.d.ts","sourceRoot":"","sources":["../../src/utils/strict-modeling.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"strict-modeling.d.ts","sourceRoot":"","sources":["../../src/utils/strict-modeling.ts"],"names":[],"mappings":"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"}

package/dist/utils/strict-modeling.js

@@ -277,7 +277,7 @@ function buildUniqueTags(tags) {
 function buildPropertyFactTitle(normalizedPropertyKey, claim) {
     const label = humanizeKey(normalizedPropertyKey);
     if (claim.operator === "polarity") {
-        return `${label} ${normalizePolarityValue(claim.value)}`;
+        return `${label} ${normalizePolarityValue(claim.value) === "forbid" ? "forbidden" : "required"}`;
     }
     const operatorLabel = claim.operator === "bool"
         ? "="
@@ -287,12 +287,19 @@ function buildPropertyFactTitle(normalizedPropertyKey, claim) {
                 ? "!="
                 : claim.operator === "gte"
                     ? ">="
-                    : "<=";
+                    : claim.operator === "gt"
+                        ? ">"
+                        : claim.operator === "lt"
+                            ? "<"
+                            : "<=";
     return `${label} ${operatorLabel} ${String(claim.value)}`;
 }
 function buildPropertyFactFields(claim) {
     if (claim.operator === "polarity") {
         return {
+            operator: "eq",
+            value_type: "bool",
+            value_bool: true,
             polarity: normalizePolarityValue(claim.value),
         };
     }
@@ -305,9 +312,22 @@ function buildPropertyFactFields(claim) {
     }
     return {
         operator: claim.operator,
-        ...buildTypedValueFields(claim.value),
+        ...buildTypedValueFields(numericClaimValue(claim)),
     };
 }
+const ORDERING_OPERATORS = new Set(["gt", "gte", "lt", "lte"]);
+// implements REQ-kibi-truthful-consistency
+// An ordering comparison is numeric by definition, so a numeric string value
+// ("0", "2.5") is stored as int/number. Stored as a string it would be
+// invisible to numeric contradiction checks.
+function numericClaimValue(claim) {
+    if (typeof claim.value === "string" &&
+        ORDERING_OPERATORS.has(claim.operator) &&
+        /^\s*-?\d+(?:\.\d+)?\s*$/.test(claim.value)) {
+        return Number(claim.value);
+    }
+    return claim.value;
+}
 function buildTypedValueFields(value) {
     if (typeof value === "boolean") {
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cli",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {
@@ -235,8 +235,8 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-core": "^0.14.1",
-    "kibi-plugin-builtin": "^0.4.0",
+    "kibi-core": "^0.15.0",
+    "kibi-plugin-builtin": "^0.4.1",
     "kibi-plugin-sdk": "^0.4.0",
     "kibi-swipl": "^1.0.0",
     "saxes": "^6.0.0",

package/schema/entities.pl

@@ -30,6 +30,9 @@ entity_property(_, severity, atom).
 entity_property(_, links, list).
 entity_property(_, text_ref, uri).
 entity_property(_, sourceFile, uri).
+% Provenance of any authored entity: a JSON object (kind, ref, approved_by,
+% recorded_at) naming who authored it and on what authority.
+entity_property(_, origin, list_or_json).
 entity_property(req, semantic_text, string).
 entity_property(req, logic_claims, list).
 entity_property(req, semantic_clauses, list).
@@ -39,6 +42,17 @@ entity_property(req, semantic_source_hash, string).
 entity_property(req, semantic_inventory, list_or_json).
 entity_property(req, proof_exempt, boolean).
 entity_property(req, proof_exempt_reason, string).
+% Human approval of an exception requirement (one that `exempts` another).
+% Only an approved exception makes a success scenario feasible.
+entity_property(req, approved_by, string).
+entity_property(req, approval_ref, string).
+% Why the requirement exists, in the words of whoever stated the intent.
+% Explanation only: it is never part of the checked meaning.
+entity_property(req, rationale, string).
+% Claim keys of the exempted requirement an exception waives (all when absent).
+entity_property(req, exempts_claims, list).
+% Intended outcome of a scenario: success, rejection or error.
+entity_property(scenario, expects, atom).
 
 % Typed fact fields - only valid for fact entities
 entity_property(fact, fact_kind, atom).
@@ -65,6 +79,9 @@ entity_property(fact, predicate_arity, integer).
 entity_property(fact, argument_names, list).
 entity_property(fact, argument_types, list).
 entity_property(fact, argument_descriptions, list).
+% Predicate-schema functional dependency: the named arguments determine the
+% remaining ones, so two atoms with equal keys describe the same fact.
+entity_property(fact, key_arguments, list).
 % Predicate-schema vocabularies are JSON objects serialized as strings.
 entity_property(fact, argument_constants, string).
 entity_property(fact, argument_aliases, string).
@@ -112,6 +129,7 @@ optional_property(Type, priority) :- entity_type(Type).
 optional_property(Type, severity) :- entity_type(Type).
 optional_property(Type, links) :- entity_type(Type).
 optional_property(Type, text_ref) :- entity_type(Type).
+optional_property(Type, origin) :- entity_type(Type).
 optional_property(req, semantic_text).
 optional_property(req, logic_claims).
 optional_property(req, semantic_clauses).
@@ -121,6 +139,10 @@ optional_property(req, semantic_source_hash).
 optional_property(req, semantic_inventory).
 optional_property(req, proof_exempt).
 optional_property(req, proof_exempt_reason).
+optional_property(req, approved_by).
+optional_property(req, approval_ref).
+optional_property(req, rationale).
+optional_property(req, exempts_claims).
 optional_property(test, verification_scope).
 optional_property(test, verification_perspective).
 optional_property(test, proof_contract).

package/schema/relationships.pl

@@ -22,6 +22,8 @@ relationship_type(constrains).
 relationship_type(requires_property).
 relationship_type(requires_predicate).
 relationship_type(requires_rule).
+relationship_type(assumes).
+relationship_type(exempts).
 
 % valid_relationship(RelType, FromType, ToType).
 valid_relationship(depends_on, req, req).
@@ -45,6 +47,18 @@ valid_relationship(requires_property, req, fact).
 valid_relationship(requires_predicate, req, fact).
 valid_relationship(requires_rule, req, fact).
 
+%% assumes(+ScenarioId, +FactId)
+%% The scenario's outcome depends on the property_value fact holding (for
+%% example "the order total is 0"). Checked against current requirements by
+%% the scenario-feasibility rule.
+% implements REQ-kibi-scenario-feasibility-v2
+valid_relationship(assumes, scenario, fact).
+
+%% exempts(+ExceptionReqId, +BaseReqId)
+%% An approved exception requirement exempts the scenarios it specifies from
+%% BaseReqId's property constraints. BaseReqId stays current and unchanged.
+valid_relationship(exempts, req, req).
+
 %% supersedes(+NewAdrId, +OldAdrId)
 %% NewAdrId is the decision that replaces OldAdrId.
 %% OldAdrId's status should be archived or deprecated as a consequence.

package/schema/validation.pl

@@ -8,6 +8,7 @@
 
 :- use_module('entities.pl').
 :- use_module('relationships.pl').
+:- use_module(library(http/json)).
 
 % validate_entity(+Type, +Props:list)
 % Props is a list of Property=Value pairs (e.g. id=ID, title=Title)
@@ -19,7 +20,9 @@ validate_entity(Type, Props) :-
     % all properties have correct types
     forall(member(Key=Val, Props), validate_property_type(Type, Key, Val)),
     % validate entity-specific shape constraints
-    validate_entity_shape(Type, Props).
+    validate_entity_shape(Type, Props),
+    % provenance, when present, names a known origin kind
+    valid_origin_in_props(Props).
 
 % validate_relationship(+RelType, +From, +To)
 % From and To are pairs Type=Id or structures type(Type) - allow Type or Type=Id
@@ -105,6 +108,7 @@ is_fact_only_field(predicate_arity).
 is_fact_only_field(argument_names).
 is_fact_only_field(argument_types).
 is_fact_only_field(argument_descriptions).
+is_fact_only_field(key_arguments).
 is_fact_only_field(argument_constants).
 is_fact_only_field(argument_aliases).
 is_fact_only_field(aliases).
@@ -156,6 +160,7 @@ validate_fact_shape(predicate_schema, Props) :-
     memberchk(argument_types=ArgumentTypes, Props),
     same_length(ArgumentNames, ArgumentTypes),
     length(ArgumentNames, Arity),
+    valid_key_arguments(Props, ArgumentNames),
     valid_optional_fact_enums(Props),
     valid_polarity_in_props(Props), !.
 validate_fact_shape(predicate, Props) :-
@@ -185,6 +190,24 @@ validate_fact_shape(Kind, _Props) :-
     \+ memberchk(Kind, [subject, property_value, observation, meta, predicate_schema, predicate, rule_schema, rule]),
     fail.
 
+% valid_key_arguments(+Props, +ArgumentNames)
+% Optional key_arguments must be a non-empty list of distinct declared
+% argument names.
+valid_key_arguments(Props, ArgumentNames) :-
+    (   memberchk(key_arguments=Keys, Props)
+    ->  is_list(Keys),
+        Keys \= [],
+        maplist(text_atom, ArgumentNames, NameAtoms),
+        maplist(text_atom, Keys, KeyAtoms),
+        sort(KeyAtoms, UniqueKeys),
+        same_length(KeyAtoms, UniqueKeys),
+        forall(member(Key, KeyAtoms), memberchk(Key, NameAtoms))
+    ;   true
+    ).
+
+text_atom(Value, Atom) :- atom(Value), !, Atom = Value.
+text_atom(Value, Atom) :- string(Value), atom_string(Atom, Value).
+
 % valid_operator(+Op)
 valid_operator(Op) :- memberchk(Op, [eq, neq, lt, lte, gt, gte]), !.
 
@@ -256,3 +279,24 @@ value_type_matches_field(string, Props) :- memberchk(value_string=_, Props), !.
 value_type_matches_field(int, Props) :- memberchk(value_int=_, Props), !.
 value_type_matches_field(number, Props) :- memberchk(value_number=_, Props), !.
 value_type_matches_field(bool, Props) :- memberchk(value_bool=_, Props), !.
+
+% valid_origin_in_props(+Props)
+% Entity provenance travels as a JSON object string (or a dict). When present
+% its kind must be human, agent, migration or import.
+valid_origin_in_props(Props) :-
+    (   memberchk(origin=Raw, Props)
+    ->  origin_kind(Raw, Kind),
+        memberchk(Kind, [human, agent, migration, import])
+    ;   true
+    ).
+
+origin_kind(Raw, Kind) :-
+    (   is_dict(Raw)
+    ->  Dict = Raw
+    ;   (atom(Raw) ; string(Raw)),
+        catch(atom_json_dict(Raw, Dict, []), _, fail),
+        is_dict(Dict)
+    ),
+    get_dict(kind, Dict, RawKind),
+    (atom(RawKind) ; string(RawKind)),
+    atom_string(Kind, RawKind).

package/src/public/branch-resolver.ts

@@ -1,2 +1,3 @@
 export * from "../utils/branch-resolver.js";
 export * from "../utils/branch-store-locator.js";
+export * from "../runtime/detached-snapshot.js";

package/src/public/diagnostic-usage.ts

@@ -1,6 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
-import { appendFileSync, mkdirSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 
 import {
   appendPayloadCountField,
@@ -241,6 +242,60 @@ export function deriveDiagnosticUsageFields(
   return fields;
 }
 
+/**
+ * Whether the operator opted into usage telemetry through the environment.
+ *
+ * `KIBI_DIAGNOSTIC_MODE` is the one opt-in shared with the MCP server, so a
+ * single setting covers both peer surfaces. `KIBI_CLI_DIAGNOSTIC_MODE` is the
+ * older CLI-only spelling and keeps working.
+ */
+export function diagnosticEnvOptIn(
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  return ["KIBI_DIAGNOSTIC_MODE", "KIBI_CLI_DIAGNOSTIC_MODE"].some((key) => {
+    const value = env[key]?.trim().toLowerCase();
+    return value === "1" || value === "true";
+  });
+}
+
+/**
+ * The host that ran this CLI call. Hosts that launch Kibi set `KIBI_HOST`;
+ * Claude Code marks every shell it runs with `CLAUDECODE=1`, which is the
+ * only ambient signal trusted here. Anything else stays `unknown`.
+ */
+export function diagnosticCliHost(
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const explicit = env.KIBI_HOST?.trim() || env.KIBI_MCP_HOST?.trim();
+  if (explicit) return explicit;
+  return env.CLAUDECODE === "1" ? "claude-code" : "unknown";
+}
+
+let cachedCliPackageVersion: string | null | undefined;
+
+function cliPackageVersion(): string | null {
+  if (cachedCliPackageVersion !== undefined) return cachedCliPackageVersion;
+  cachedCliPackageVersion = null;
+  let current = path.dirname(fileURLToPath(import.meta.url));
+  while (true) {
+    const candidate = path.join(current, "package.json");
+    if (existsSync(candidate)) {
+      try {
+        const parsed: unknown = JSON.parse(readFileSync(candidate, "utf8"));
+        if (isRecord(parsed) && typeof parsed.version === "string") {
+          cachedCliPackageVersion = parsed.version;
+        }
+      } catch {
+        // An unreadable manifest leaves the version unknown.
+      }
+      return cachedCliPackageVersion;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
 export function appendCliDiagnosticUsage(input: DiagnosticUsageInput): void {
   const finishedAt = input.finishedAt ?? new Date();
   const requestId = input.requestId ?? `cli-${randomUUID()}`;
@@ -256,6 +311,9 @@ export function appendCliDiagnosticUsage(input: DiagnosticUsageInput): void {
       request_id: requestId,
       tool: input.tool,
       interface: "cli_json",
+      host: diagnosticCliHost(),
+      package_version: cliPackageVersion(),
+      workspace_root: input.workspaceRoot,
       telemetry: input.telemetry,
       business_args: input.businessArgs,
       status: input.status,