kibi-cli 2.4.0 → 2.5.1

package/src/public/skills/kibi-usage/resources/workflows.md

@@ -35,21 +35,22 @@ edits dependency configuration.
 
 ## Choosing a discovery mode
 
-`kb_search` is not one behavior. It selects deterministic intent ranking when
-you pass `rankingMode: "intent-v1"`, `semanticFacets`, or `sourceLocations`,
-and legacy lexical ranking otherwise. Naming the tool is not enough; the inputs
-decide the path.
+`kb_search` defaults to deterministic intent ranking (`rankingMode:
+"intent-v1"`), so a natural-language question is a valid query. Pass
+`rankingMode: "legacy"` for the older lexical ranking. The inputs, not the tool
+name, decide how results are ranked.
 
 - **Exact identity** — you already know the ID. Use `kb_query`, not search.
 - **Literal token** — a symbol, file, or error string that appears verbatim.
-  Use lexical `kb_search` and keep the query close to the literal text.
-- **Conceptual or behavioral** — "how does checkout handle a declined card".
-  Use intent mode and ground it in what you actually know:
+  Keep the query close to the literal text; `rankingMode: "legacy"` ranks it
+  lexically.
+- **Question or behavior** — "what governs how checkout handles a declined
+  card?". Ask it directly, and ground it with facets from what you actually
+  know:
 
 ```json
 {
-  "query": "declined card during checkout",
-  "rankingMode": "intent-v1",
+  "query": "what governs a declined card during checkout?",
   "semanticFacets": {
     "actors": ["shopper"],
     "actions": ["pay"],
@@ -66,7 +67,6 @@ decide the path.
 ```json
 {
   "query": "checkout total rounding",
-  "rankingMode": "intent-v1",
   "sourceLocations": [{ "path": "src/checkout.ts", "symbol": "computeTotal" }]
 }
 ```
@@ -75,8 +75,25 @@ Supply facets only from the request, the code, or prior results. Inventing
 facets fabricates evidence and biases ranking. Intent mode abstains below
 `minScore` instead of returning weak matches; an abstention is an explicit
 no-answer, so widen the query or drop to lexical search rather than treating it
-as "nothing exists". There is no target percentage of intent-mode calls — a
-literal identifier lookup is still best served lexically.
+as "nothing exists". A literal identifier lookup is still best served
+lexically.
+
+On the first page, intent mode also returns an answer layer in `data.answer`
+(`kibi.search-answer.v1`; turn it off with `answer: false`):
+
+- `governing` — current requirements matched by the query or linked to a
+  matched entity, each with `via` (how it was reached) and its linked `facts`,
+  `scenarios`, `tests`, and `adrs`.
+- `rationale` — ADRs that explain the decisions.
+- `notGoverning` — superseded or deprecated requirements, with `supersededBy`
+  when known. Never read these as current policy; superseded entities are also
+  demoted in the ranked results.
+- `observations` — observation/meta facts, which are notes, not rules.
+- `truncated` and `note` — the layer is size-bounded; an empty `governing`
+  list is not evidence that nothing governs the change.
+
+The answer layer is graph traversal: discovery, not proof. Use `kb_check` and
+`kb_coverage` for consistency and proof status.
 
 Results are summaries by default: identifying metadata, score, reasons, and a
 snippet. Read them to pick candidates, then `kb_query` those IDs for full
@@ -88,12 +105,12 @@ planning a behavior change; a search receipt is not comprehension.
 
 The canonical workflow for any KB operation follows this pattern:
 
-1. **Discover**: `kb_search` with focused probes; pick the mode above
+1. **Discover**: `kb_search` with focused probes or a direct question; read `data.answer`, and pick the mode above
 2. **Confirm**: `kb_query` for exact IDs and state
 3. **Inspect**: `kb_status` when freshness matters
-4. **Decompose**: `kb_semantic_advisor` on the complete normative prose; verify or supply every atomic clause
-5. **Choose per-clause lanes**: strict facts for scalar claims; `kb_suggest_predicates` for approved ground ontology relations; `kb_model_requirement` with `kibi.logic.v1` for conditions, exceptions, modalities, quantifiers, cardinality, and bounded temporal rules; observation review for ambiguity, nonlogical prose, and ontology gaps
-6. **Preflight**: `kb_validate_upsert` for every intended entity or relationship payload
+4. **Decompose**: `kb_model` (`mode: "analyze"`) on the complete normative prose; verify or supply every atomic clause
+5. **Choose per-clause lanes**: strict facts for scalar claims; `kb_model` `mode: "predicates"` for approved ground ontology relations; `kb_model` `mode: "requirement"` with `kibi.logic.v1` for conditions, exceptions, modalities, quantifiers, cardinality, and bounded temporal rules; observation review for ambiguity, nonlogical prose, and ontology gaps
+6. **Preflight**: `kb_upsert` with `dryRun: true` for every intended entity or relationship payload
 7. **Create endpoints**: validated `kb_upsert` for new entities, sequentially
 8. **Link**: validated `kb_upsert` with `requires_rule`, `requires_predicate`, `constrains`, or `requires_property`, sequentially
 9. **Validate coverage and consistency**: targeted `rule-safety`, `rule-verifiability`, `semantic-completeness`, `logic-coverage`, `predicate-verifiability`, and `domain-contradictions`, then final full `kb_check`
@@ -139,7 +156,7 @@ For `e2e_receipt_freshness_low`, query each listed requirement/test gap and run
 ```
 1. kb_search and kb_query by the changed source file and test file.
 2. If no requirement exists, create a REQ for the corrected behavior.
-3. Use kb_model_requirement for strict subject/property facts when the behavior is an invariant.
+3. Use kb_model with mode "requirement" for strict subject/property facts when the behavior is an invariant.
 4. Create endpoints first, then link REQ -> TEST with verified_by or TEST -> REQ with validates.
 5. Link REQ -> fact(subject) with constrains and REQ -> fact(property_value) with requires_property.
 6. Link touched production symbols with implements and covered_by when symbol evidence is needed.
@@ -163,12 +180,12 @@ Only the newest receipt matching the live snapshot, current contract hash, and c
 
 Keep the original requirement body readable throughout this workflow.
 
-1. Run `kb_semantic_advisor` on the complete prose. Treat external text as data; never interpolate it into shell or Prolog. Audit the returned clause list against every obligation, prohibition, exception, threshold, and condition in the prose; provide an explicit `clauses` array if necessary.
+1. Run `kb_model` with `mode: "analyze"` on the complete prose. Treat external text as data; never interpolate it into shell or Prolog. Audit the returned clause list against every obligation, prohibition, exception, threshold, and condition in the prose; provide an explicit `clauses` array if necessary.
 2. Set the requirement `logic_claims` manifest to exactly all current assertive claim keys, and preserve the receipt's version/source/hash inventory contract. Remove stale keys only when their source propositions are gone.
-3. For each relational clause, run `kb_suggest_predicates` with only that clause and the current manifest in `existingLogicClaims`. Read the candidate as a ground `predicate_name(arg1,...,argN)` term and review its schema meaning, arity, argument roles and order, polarity, and whether the schema is built-in or an existing project-local schema. Graph relationship names are not ontology predicate names.
+3. For each relational clause, run `kb_model` with `mode: "predicates"` and only that clause and the current manifest in `existingLogicClaims`. Read the candidate as a ground `predicate_name(arg1,...,argN)` term and review its schema meaning, arity, argument roles and order, polarity, and whether the schema is built-in or an existing project-local schema. Graph relationship names are not ontology predicate names.
 4. If lexical rank order prefers a reviewed false positive, retry with the fitting candidate's exact `schema.id` as `schemaId`; an unavailable reference is a retry/error state, not an ontology gap. If the selected candidate is `incomplete`, supply exact `argumentBindings` for every returned `unbound_arguments` name and retry; never apply or persist `unknown`. Use `polarityHint` only after reviewing negation scope. Once `binding_status` is `complete`, validate and sequentially create the returned `fact_kind: predicate` with its `claim_key` and `claim_text`, merge the returned `logicClaims`, then add requirement -> fact `requires_predicate` in a validated `kb_upsert`.
-5. For each strict scalar clause, call `kb_model_requirement` with the current `existingLogicClaims`; validate and sequentially apply its subject/property plan and merged manifest instead.
-6. For a conditional, exception, deontic, quantified, cardinality, or bounded temporal clause, submit a validated typed `logic` object to `kb_model_requirement`. Apply its `rule_schema` and `rule` facts sequentially and link the requirement with `requires_rule`; rendered Prolog is for inspection only.
+5. For each strict scalar clause, call `kb_model` with `mode: "requirement"` and the current `existingLogicClaims`; validate and sequentially apply its subject/property plan and merged manifest instead.
+6. For a conditional, exception, deontic, quantified, cardinality, or bounded temporal clause, submit a validated typed `logic` object to `kb_model` with `mode: "requirement"`. Apply its `rule_schema` and `rule` facts sequentially and link the requirement with `requires_rule`; rendered Prolog is for inspection only.
 7. If wording is ambiguous, a candidate is only a lexical false positive, or no schema/IR interpretation fits, create the advised observation review artifact and apply its returned `relates_to` review anchor when present; report that claim key as unresolved. Use `review:ambiguity` for unresolved interpretation, `review:keyword-false-positive` for a vocabulary match that is not a domain assertion, and `review:ontology-gap` only for a true catalog gap. Define a new `predicate_schema` only when the task explicitly authorizes ontology extension and provides a stable signature.
 8. Read back the requirement, proposition ledger, and all facts. Confirm every manifest key occurs on exactly one intended ground fact/rule, no punctuation variant minted a second claim, and no two claim keys encode the same logical term. Exact query output may represent repeated relationship types as arrays, so inspect every target. Then run `kb_check` with `rule-safety`, `rule-verifiability`, `semantic-completeness`, `logic-coverage`, `predicate-verifiability`, and `domain-contradictions`. Finish with an unfiltered `kb_check`.
 
@@ -183,12 +200,12 @@ On resume after interruption, repeat `kb_query` for exact endpoints and apply on
 Optional per-project workflow for recording what the screen should look like. Non-UI projects skip this lane entirely.
 
 1. Create a prose `req` holding the full visual description; it is the searchable anchor agents discover before touching a UI file.
-2. Run `kb_semantic_advisor` on the description; audit or supply `clauses`.
-3. For relational layout clauses ("X must remain visually aligned with Y"), call `kb_suggest_predicates`, apply the returned `fact_kind: predicate` plan with `predicate_name: visual_layout_rule` and `requires_predicate`.
-4. For scalar placement, alignment, and ordering clauses, call `kb_model_requirement` and apply strict `fact_kind: subject` / `fact_kind: property_value` facts linked with `constrains` / `requires_property`. Model header order as indexed property keys (`nav_order_1`, `nav_order_2`, ...) against one subject region.
+2. Run `kb_model` with `mode: "analyze"` on the description; audit or supply `clauses`.
+3. For relational layout clauses ("X must remain visually aligned with Y"), call `kb_model` with `mode: "predicates"`, apply the returned `fact_kind: predicate` plan with `predicate_name: visual_layout_rule` and `requires_predicate`.
+4. For scalar placement, alignment, and ordering clauses, call `kb_model` with `mode: "requirement"` and apply strict `fact_kind: subject` / `fact_kind: property_value` facts linked with `constrains` / `requires_property`. Model header order as indexed property keys (`nav_order_1`, `nav_order_2`, ...) against one subject region.
 5. Preserve `claim_key` / `claim_text` on every ground fact and merge every key into the requirement `logic_claims` manifest.
 6. Model UI components as `symbol` entities with `sourceFile` and `symbol_role: behavioral`, linked `implements` to the requirement.
-7. `kb_validate_upsert`, create endpoints first, then sequential `kb_upsert`. Run `kb_check` with `logic-coverage`, `predicate-verifiability`, and `domain-contradictions`, then a final unfiltered `kb_check`.
+7. `kb_upsert` with `dryRun: true`, create endpoints first, then sequential `kb_upsert`. Run `kb_check` with `logic-coverage`, `predicate-verifiability`, and `domain-contradictions`, then a final unfiltered `kb_check`.
 
 Incompatible values on the same subject/property from two current requirements are rejected on write; change an intentional value via a replacement requirement linked with `supersedes`. Full payloads are in `resources/ui-requirements.md`.
 

package/src/public/telemetry-acceptance-types.d.ts

@@ -1,4 +1,4 @@
-// implements REQ-kibi-telemetry-acceptance-gate
+// implements REQ-kibi-telemetry-acceptance-gate-v2
 export type TelemetryMetricStatus =
   | "passed"
   | "failed"
@@ -14,6 +14,7 @@ export type TelemetryMetricId =
   | "telemetry_completeness"
   | "advisor_before_requirement_write"
   | "validation_before_upsert"
+  | "lookup_before_first_edit"
   | "source_lookup_zero_result_rate"
   | "proof_gap_recovery"
   | "e2e_receipt_freshness"
@@ -59,6 +60,8 @@ export interface TelemetryAcceptancePolicy {
   readonly telemetryCompletenessMinimum: number;
   readonly validationBeforeUpsertMinimum: number;
   readonly advisorBeforeRequirementWriteMinimum: number;
+  /** Share of host sessions that ran kb_search or kb_query before their first requirement-linked edit. */
+  readonly lookupBeforeFirstEditMinimum: number;
   readonly sourceLookupZeroResultMaximum: number;
   readonly preflightMaxAgeSeconds: number;
   readonly advisorMaxAgeSeconds: number;

package/src/public/telemetry-acceptance.ts

@@ -30,6 +30,7 @@ export const DEFAULT_TELEMETRY_ACCEPTANCE_POLICY = {
   telemetryCompletenessMinimum: 0.95,
   validationBeforeUpsertMinimum: 1,
   advisorBeforeRequirementWriteMinimum: 1,
+  lookupBeforeFirstEditMinimum: 1,
   sourceLookupZeroResultMaximum: 0.2,
   preflightMaxAgeSeconds: 60 * 60,
   advisorMaxAgeSeconds: 24 * 60 * 60,
@@ -50,18 +51,67 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 
+// implements REQ-kibi-telemetry-acceptance-gate-v2, REQ-claude-hook-usage-telemetry-v2
+/**
+ * A row written by a host plugin hook (`interface: "hook"`). Hooks record
+ * agent activity around Kibi calls: which Kibi operation a tool call ran
+ * (`hook_action: "kb_usage"`) and which files an edit tool changed, with the
+ * requirements those files' symbols implement (`hook_action: "edited"`).
+ */
+export interface TelemetryHookEvent extends TelemetryUsageEvent {
+  readonly interface?: string;
+  readonly host?: string;
+  readonly hook_action?: string;
+  readonly path?: string | null;
+  readonly requirement_ids?: readonly string[];
+  readonly kb_operation?: string | null;
+}
+
+// implements REQ-kibi-telemetry-acceptance-gate-v2, REQ-claude-hook-usage-telemetry-v2
+/** A host hook row and where it sits relative to the operation events. */
+export interface TelemetryHookRow {
+  readonly event: TelemetryHookEvent;
+  /** 1-based `.kb/usage.log` line (array position for in-memory events). */
+  readonly logLine: number;
+  /** Operation events that precede this row in the log. */
+  readonly operationsBefore: number;
+}
+
+// implements REQ-kibi-telemetry-acceptance-gate-v2, REQ-claude-hook-usage-telemetry-v2
+/** Operation events and host hook rows of one usage log, kept apart. */
+export interface TelemetryUsagePartition {
+  readonly operations: readonly TelemetryUsageEvent[];
+  /** 1-based `.kb/usage.log` line of each operation event. */
+  readonly operationLines: readonly number[];
+  readonly hookRows: readonly TelemetryHookRow[];
+}
+
+/**
+ * Hook rows and line numbers of every array `parseTelemetryUsageLog`
+ * returned. The array itself keeps its operation-only shape, so callers that
+ * pass it straight to the analyzers need no change.
+ */
+const parsedUsageLogs = new WeakMap<
+  readonly TelemetryUsageEvent[],
+  Omit<TelemetryUsagePartition, "operations">
+>();
+
 /**
  * Parse Kibi operation events from `.kb/usage.log`.
  *
  * Host plugin hooks share the log and tag their rows `interface: "hook"`.
  * Those rows describe agent activity around Kibi calls, not Kibi operations,
- * so they are dropped here: otherwise a busy editing session would push every
- * operation out of the bounded acceptance window.
+ * so they are left out of the returned array: otherwise a busy editing
+ * session would push every operation out of the bounded acceptance window.
+ * They stay attached to the array for `partitionTelemetryUsage`, which is how
+ * the `lookup_before_first_edit` metric reads them.
  */
 export function parseTelemetryUsageLog(
   contents: string,
 ): TelemetryUsageEvent[] {
   const events: TelemetryUsageEvent[] = [];
+  const operationLines: number[] = [];
+  const hookRows: TelemetryHookRow[] = [];
   for (const [index, line] of contents.split(/\r?\n/).entries()) {
     const trimmed = line.trim();
     if (!trimmed) continue;
@@ -79,12 +129,50 @@ export function parseTelemetryUsageLog(
         `Failed to parse .kb/usage.log line ${index + 1}: expected object`,
       );
     }
-    if (parsed.interface === "hook") continue;
+    if (parsed.interface === "hook") {
+      hookRows.push({
+        event: parsed as TelemetryHookEvent,
+        logLine: index + 1,
+        operationsBefore: events.length,
+      });
+      continue;
+    }
     events.push(parsed as TelemetryUsageEvent);
+    operationLines.push(index + 1);
   }
+  parsedUsageLogs.set(events, { operationLines, hookRows });
   return events;
 }
 
+// implements REQ-kibi-telemetry-acceptance-gate-v2, REQ-claude-hook-usage-telemetry-v2
+/**
+ * Split events into Kibi operations and host hook rows. Arrays from
+ * `parseTelemetryUsageLog` carry their hook rows and log lines; any other
+ * array is split on `interface: "hook"`, with positions as line numbers.
+ */
+export function partitionTelemetryUsage(
+  events: readonly TelemetryUsageEvent[],
+): TelemetryUsagePartition {
+  const parsed = parsedUsageLogs.get(events);
+  if (parsed !== undefined) return { operations: events, ...parsed };
+  const operations: TelemetryUsageEvent[] = [];
+  const operationLines: number[] = [];
+  const hookRows: TelemetryHookRow[] = [];
+  for (const [index, event] of events.entries()) {
+    if ((event as TelemetryHookEvent).interface === "hook") {
+      hookRows.push({
+        event: event as TelemetryHookEvent,
+        logLine: index + 1,
+        operationsBefore: operations.length,
+      });
+    } else {
+      operations.push(event);
+      operationLines.push(index + 1);
+    }
+  }
+  return { operations, operationLines, hookRows };
+}
+
 function eventArgs(
   event: TelemetryUsageEvent,
 ): Readonly<Record<string, unknown>> {
@@ -372,6 +460,103 @@ function advisorBeforeRequirementWriteMetric(
   };
 }
 
+// implements REQ-kibi-telemetry-acceptance-gate-v2
+/** Kibi operations that count as looking up requirements before an edit. */
+export const LOOKUP_BEFORE_EDIT_OPERATIONS = ["kb_query", "kb_search"] as const;
+
+// implements REQ-kibi-telemetry-acceptance-gate-v2
+/** The first requirement-linked edit of one host session. */
+export interface FirstLinkedEdit {
+  /** `<host>:<session_id>` of the session. */
+  readonly session: string;
+  readonly edit: TelemetryHookRow;
+  /** True when kb_search or kb_query ran earlier in the same session. */
+  readonly lookedUp: boolean;
+}
+
+function hookSession(event: TelemetryHookEvent): string | undefined {
+  const sessionId = event.session_id;
+  if (typeof sessionId !== "string" || sessionId.length === 0) return undefined;
+  return `${event.host ?? "unknown"}:${sessionId}`;
+}
+
+// implements REQ-kibi-telemetry-acceptance-gate-v2, REQ-claude-hook-usage-telemetry-v2
+/**
+ * For each host session, its first edit of a file whose symbols implement a
+ * requirement and whether a Kibi lookup (MCP or CLI) preceded it. Rows
+ * without a session id cannot be ordered within a session and are skipped;
+ * sessions whose first linked edit predates the evaluated window are left
+ * out.
+ */
+export function firstLinkedEdits(
+  hookRows: readonly TelemetryHookRow[],
+  recentStart: number,
+): FirstLinkedEdit[] {
+  const lookedUp = new Set<string>();
+  const edited = new Set<string>();
+  const firstEdits: FirstLinkedEdit[] = [];
+  for (const row of hookRows) {
+    const session = hookSession(row.event);
+    if (session === undefined) continue;
+    const { hook_action: action, kb_operation: operation } = row.event;
+    if (
+      action === "kb_usage" &&
+      LOOKUP_BEFORE_EDIT_OPERATIONS.some((candidate) => candidate === operation)
+    ) {
+      lookedUp.add(session);
+      continue;
+    }
+    if (
+      action !== "edited" ||
+      edited.has(session) ||
+      !Array.isArray(row.event.requirement_ids) ||
+      row.event.requirement_ids.length === 0
+    ) {
+      continue;
+    }
+    edited.add(session);
+    if (row.operationsBefore < recentStart) continue;
+    firstEdits.push({ session, edit: row, lookedUp: lookedUp.has(session) });
+  }
+  return firstEdits;
+}
+
+function lookupBeforeFirstEditMetric(
+  hookRows: readonly TelemetryHookRow[],
+  recentStart: number,
+  policy: TelemetryAcceptancePolicy,
+): MutableMetric {
+  const firstEdits = firstLinkedEdits(hookRows, recentStart);
+  const attempts = firstEdits.length;
+  const guided = firstEdits.filter((entry) => entry.lookedUp).length;
+  const unguidedEditPaths = new Set(
+    firstEdits
+      .filter((entry) => !entry.lookedUp)
+      .map((entry) => entry.edit.event.path ?? "unknown path"),
+  );
+
+  const actual = rate(guided, attempts);
+  return {
+    id: "lookup_before_first_edit",
+    status: thresholdStatus(actual, ">=", policy.lookupBeforeFirstEditMinimum),
+    numerator: guided,
+    denominator: attempts,
+    ...(actual !== undefined ? { rate: actual } : {}),
+    threshold: {
+      operator: ">=",
+      value: policy.lookupBeforeFirstEditMinimum,
+    },
+    message:
+      attempts === 0
+        ? "No host hook recorded an edit of a requirement-linked file in the evaluated window."
+        : `${guided}/${attempts} sessions ran kb_search or kb_query before their first edit of a requirement-linked file.`,
+    evidence: {
+      unguidedEditPaths: [...unguidedEditPaths].sort().slice(0, 20),
+      lookupOperations: [...LOOKUP_BEFORE_EDIT_OPERATIONS],
+    },
+  };
+}
+
 function sourceLookupMessage(
   zeroResults: number,
   lookups: number,
@@ -629,7 +814,8 @@ export function analyzeTelemetryAcceptance(
   now: Date = new Date(),
   policy: TelemetryAcceptancePolicy = DEFAULT_TELEMETRY_ACCEPTANCE_POLICY,
 ): TelemetryAcceptanceReport {
-  const all = events.map((event, index) => ({
+  const { operations, hookRows } = partitionTelemetryUsage(events);
+  const all = operations.map((event, index) => ({
     event,
     index,
     time: timestampMillis(event.timestamp),
@@ -653,14 +839,15 @@ export function analyzeTelemetryAcceptance(
     telemetryCompletenessMetric(recent, policy),
     advisorBeforeRequirementWriteMetric(all, recentStart, policy),
     validationBeforeUpsertMetric(all, recentStart, policy),
+    lookupBeforeFirstEditMetric(hookRows, recentStart, policy),
     sourceLookupMetric(recent, policy),
     proofGapRecoveryMetric(recent),
     receiptFreshnessMetric(recent),
     repeatedMutationFailuresMetric(recent, policy),
   ];
   const diagnostics: string[] = [];
-  if (events.length === 0) diagnostics.push("usage_log_empty");
-  if (lastTime === null && events.length > 0) {
+  if (operations.length === 0) diagnostics.push("usage_log_empty");
+  if (lastTime === null && operations.length > 0) {
     diagnostics.push("usage_log_timestamps_unavailable");
   } else if (!fresh) {
     diagnostics.push(
@@ -676,9 +863,9 @@ export function analyzeTelemetryAcceptance(
     evaluatedAt: now.toISOString(),
     policy,
     scope: {
-      totalEvents: events.length,
+      totalEvents: operations.length,
       evaluatedEvents: recent.length,
-      truncated: events.length > recent.length,
+      truncated: operations.length > recent.length,
       firstTimestamp:
         firstTime === null ? null : new Date(firstTime).toISOString(),
       lastTimestamp:
@@ -713,14 +900,21 @@ const METRIC_DIAGNOSTICS: Readonly<
     severity: "warning",
     rank: 30,
     suggestion:
-      "Run kb_semantic_advisor on the complete current requirement prose before its next upsert, preserve the returned source hash, and recheck telemetry.",
+      "Run kb_model with mode analyze (CLI: semantic-advisor) on the complete current requirement prose before its next upsert, preserve the returned source hash, and recheck telemetry.",
   },
   validation_before_upsert: {
     id: "mutation_validation_bypassed",
     severity: "warning",
     rank: 20,
     suggestion:
-      "Run kb_validate_upsert for the exact payload no more than one hour before each sequential kb_upsert attempt.",
+      "Run kb_upsert with dryRun true (CLI: validate-upsert) for the exact payload no more than one hour before each sequential kb_upsert attempt.",
+  },
+  lookup_before_first_edit: {
+    id: "lookup_before_first_edit_bypassed",
+    severity: "warning",
+    rank: 35,
+    suggestion:
+      "Before a session's first edit of a requirement-linked file, run kb_search for the change (or kb_query with sourceFile for the file) and read the requirements it names; host hook rows in diagnostic mode record the order.",
   },
   source_lookup_zero_result_rate: {
     id: "source_lookup_zero_result_rate_high",

package/src/public/telemetry-remediation.ts

@@ -6,6 +6,8 @@ import {
   type TelemetryMetricId,
   type TelemetryUsageEvent,
   analyzeTelemetryAcceptance,
+  firstLinkedEdits,
+  partitionTelemetryUsage,
 } from "./telemetry-acceptance.js";
 
 export const TELEMETRY_REMEDIATION_VERSION =
@@ -46,6 +48,8 @@ export interface TelemetryRemediationReport {
 type IndexedEvent = {
   readonly event: TelemetryUsageEvent;
   readonly index: number;
+  /** 1-based `.kb/usage.log` line, counting host hook rows and blank lines. */
+  readonly logLine: number;
   readonly time: number | null;
 };
 
@@ -55,6 +59,7 @@ const RANKS: Readonly<
   repeated_mutation_failures: 10,
   validation_before_upsert: 20,
   advisor_before_requirement_write: 30,
+  lookup_before_first_edit: 35,
   e2e_receipt_freshness: 40,
   proof_gap_recovery: 50,
   source_lookup_zero_result_rate: 60,
@@ -138,7 +143,7 @@ function target(event: TelemetryUsageEvent): string {
 
 function reference(entry: IndexedEvent): TelemetryRemediationEventReference {
   return {
-    logLine: entry.index + 1,
+    logLine: entry.logLine,
     requestId: entry.event.request_id ?? null,
     timestamp: entry.event.timestamp ?? null,
     tool: entry.event.tool ?? null,
@@ -155,7 +160,7 @@ function eventItem(
   action: string,
 ): TelemetryRemediationItem {
   return {
-    id: `${metric}:line-${entry.index + 1}:${itemTarget}`,
+    id: `${metric}:line-${entry.logLine}:${itemTarget}`,
     rank: RANKS[metric],
     metric,
     scope: "event",
@@ -200,14 +205,18 @@ export function buildTelemetryRemediationReport(
   policy: TelemetryAcceptancePolicy = DEFAULT_TELEMETRY_ACCEPTANCE_POLICY,
 ): TelemetryRemediationReport {
   const acceptance = analyzeTelemetryAcceptance(events, now, policy);
-  const all: IndexedEvent[] = events.map((event, index) => ({
+  const { operations, operationLines, hookRows } =
+    partitionTelemetryUsage(events);
+  const timeOf = (event: TelemetryUsageEvent): number | null =>
+    event.timestamp === undefined ||
+    !Number.isFinite(Date.parse(event.timestamp))
+      ? null
+      : Date.parse(event.timestamp);
+  const all: IndexedEvent[] = operations.map((event, index) => ({
     event,
     index,
-    time:
-      event.timestamp === undefined ||
-      !Number.isFinite(Date.parse(event.timestamp))
-        ? null
-        : Date.parse(event.timestamp),
+    logLine: operationLines[index] ?? index + 1,
+    time: timeOf(event),
   }));
   const recentStart = Math.max(0, all.length - policy.eventLimit);
   const recent = all.slice(recentStart);
@@ -277,7 +286,7 @@ export function buildTelemetryRemediationReport(
             entry,
             target(entry.event),
             "No recent successful preflight matches this exact payload and correlation context.",
-            "Run kb_validate_upsert for this exact payload in the same session/actor context before retrying once.",
+            "Run kb_upsert with dryRun true (CLI: validate-upsert) for this exact payload in the same session/actor context before retrying once.",
           ),
         );
       }
@@ -328,13 +337,33 @@ export function buildTelemetryRemediationReport(
             entry,
             requirementId,
             "No recent semantic-advisor event matches this requirement, source hash, and correlation context.",
-            "Run kb_semantic_advisor on the complete prose in the same session/actor context before the next upsert.",
+            "Run kb_model with mode analyze (CLI: semantic-advisor) on the complete prose in the same session/actor context before the next upsert.",
           ),
         );
       }
     }
   }
 
+  if (isActionable(acceptance, "lookup_before_first_edit")) {
+    for (const { edit, lookedUp } of firstLinkedEdits(hookRows, recentStart)) {
+      if (lookedUp) continue;
+      items.push(
+        eventItem(
+          "lookup_before_first_edit",
+          {
+            event: edit.event,
+            index: edit.operationsBefore,
+            logLine: edit.logLine,
+            time: timeOf(edit.event),
+          },
+          edit.event.path ?? "unknown path",
+          "This session edited a requirement-linked file before any kb_search or kb_query.",
+          "Before the next edit of this file, run kb_search for the change or kb_query with this sourceFile, and read the requirements it names.",
+        ),
+      );
+    }
+  }
+
   if (isActionable(acceptance, "source_lookup_zero_result_rate")) {
     for (const entry of recent) {
       const sourceFile = args(entry.event).sourceFile;