kibi-cli 2.0.0 → 2.2.0

package/src/public/skills/kibi-usage/resources/relationship-directions.md

@@ -12,6 +12,7 @@
 | `constrains` | req -> fact(subject) | Requirement constrains a strict-lane domain fact |
 | `requires_property` | req -> fact(property_value) | Requirement requires a specific property value fact |
 | `supersedes` | new-req -> old-req | New requirement formally replaces an old requirement |
+| `restates` | req -> req | Requirement intentionally restates another current requirement (for example a product requirement echoed in a platform requirement); suppresses `domain-redundancy` for that pair without retiring either side |
 | `covered_by` | symbol -> test | Production symbol has test coverage evidence |
 
 ## Valid Payload Examples
@@ -20,32 +21,32 @@
 ```yaml
 relationships:
   - type: implements
-    from: SYM-001
-    to: REQ-001
+    from: SYM-operation-execute-check
+    to: REQ-cli-check
 ```
 
 ### specified_by
 ```yaml
 relationships:
   - type: specified_by
-    from: REQ-001
-    to: SCEN-001
+    from: REQ-mcp-search-discovery
+    to: SCEN-mcp-search-discovery
 ```
 
 ### verified_by
 ```yaml
 relationships:
   - type: verified_by
-    from: REQ-001
-    to: TEST-001
+    from: REQ-mcp-search-discovery
+    to: TEST-mcp-search-discovery
 ```
 
 ### validates
 ```yaml
 relationships:
   - type: validates
-    from: TEST-001
-    to: SCEN-001
+    from: TEST-mcp-search-discovery
+    to: SCEN-mcp-search-discovery
 ```
 
 ### executable_for
@@ -53,39 +54,56 @@ relationships:
 relationships:
   - type: executable_for
     from: SYM-test-login
-    to: TEST-001
+    to: TEST-mcp-search-discovery
 ```
 
 ### constrains
 ```yaml
 relationships:
   - type: constrains
-    from: REQ-019
-    to: FACT-USER-ROLE
+    from: REQ-cli-check
+    to: FACT-SUBJECT-KIBI-CHECK
 ```
 
 ### requires_property
 ```yaml
 relationships:
   - type: requires_property
-    from: REQ-019
-    to: FACT-LIMIT-3
+    from: REQ-cli-check
+    to: FACT-PROP-CHECK-FAILURE-EXIT-CODE
 ```
 
 ### supersedes
 ```yaml
 relationships:
   - type: supersedes
-    from: REQ-001-v2
-    to: REQ-001
+    from: REQ-opencode-kibi-briefing-v2
+    to: REQ-opencode-kibi-briefing-v1
 ```
 
+A `-v2` suffix is acceptable only for a direct superseding replacement like
+this one; otherwise name the new requirement by the behavior it governs.
+
+### restates
+```yaml
+# Illustrative: a product requirement echoes a platform requirement verbatim.
+relationships:
+  - type: restates
+    from: REQ-billing-invoice-retention
+    to: REQ-platform-record-retention
+```
+
+Use `restates` only when two current requirements deliberately ground the same
+logical term (same predicate, property tuple, or rule semantic key). It keeps
+both requirements current and tells `domain-redundancy` the duplication is
+intentional. If one requirement replaces the other, use `supersedes` instead.
+
 ### covered_by
 ```yaml
 relationships:
   - type: covered_by
-    from: SYM-handler
-    to: TEST-005
+    from: SYM-operation-execute-check
+    to: TEST-mcp-search-discovery
 ```
 
 ## Invalid Test-Fact Shortcuts

package/src/public/skills/kibi-usage/resources/source-authoring.md

@@ -29,3 +29,39 @@ Cancellation follows the same rule: wait for the terminal journal state. A
 pre-commit rollback is retryable, a committed source with a failed derivative
 is repairable, and an indeterminate outcome is non-retryable until its recovery
 action resolves the journal.
+
+## Naming entities
+
+Name every entity by what it governs, the way you would name a source file.
+Never choose "the next number": parallel branches pick the same next number and
+collide even when they touch unrelated behavior.
+
+- Use `<TYPE>-<area>-<behavior>` in kebab-case, with the type prefix kept
+  uppercase: `REQ-cli-gc`, `SCEN-mcp-search-discovery`,
+  `TEST-mcp-search-discovery`, `ADR-capability-plugins-v1`,
+  `EVT-exact-branch-store-ensure`, and a flag named after its gate such as
+  `FLAG-scip-symbol-extraction`.
+- The filename stem equals the frontmatter `id`
+  (`.kb/requirements/REQ-cli-gc.md` has `id: REQ-cli-gc`). Always set `id`
+  explicitly; a missing `id` falls back to a path-and-title hash that changes
+  when the file is renamed.
+- Before creating an entity, `kb_search` the area. If an existing entity already
+  covers the behavior, update it, or create a replacement and link it with
+  `supersedes`. A `-v2` suffix is acceptable only for that direct superseding
+  replacement.
+- A name collision with another branch usually means the same work was done
+  twice. Reconcile the two entities; do not rename one of them to dodge the
+  collision.
+- The area prefix is for humans. Whether two requirements are about the same
+  thing is decided by their facts: a shared `subject_key` and identical
+  predicate or property signatures, which `domain-redundancy` and
+  `domain-contradictions` compare deterministically. Reuse existing subject keys
+  (dotted `component.aspect[.sub]`, lowercase snake segments such as
+  `kibi.cli.check.staged`) instead of deriving a subject from the requirement
+  ID.
+
+`entity-id-style` reports new purely numeric IDs (`REQ-123`) and IDs whose
+filename stem differs from `id` as non-blocking quality diagnostics. Legacy
+numbered entities created before the naming standard are grandfathered and are
+not renamed, because code comments such as `// implements REQ-003` still
+reference them.

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

@@ -33,11 +33,62 @@ surfaces are a release defect: require a new package version and label any
 project override temporary. This skill never selects a package manager or
 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.
+
+- **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:
+
+```json
+{
+  "query": "declined card during checkout",
+  "rankingMode": "intent-v1",
+  "semanticFacets": {
+    "actors": ["shopper"],
+    "actions": ["pay"],
+    "objects": ["card"],
+    "constraints": ["declined"]
+  }
+}
+```
+
+- **Before changing code** — pass the file you are about to edit as a source
+  location, so results are matched against source-linked symbols and return
+  source evidence:
+
+```json
+{
+  "query": "checkout total rounding",
+  "rankingMode": "intent-v1",
+  "sourceLocations": [{ "path": "src/checkout.ts", "symbol": "computeTotal" }]
+}
+```
+
+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.
+
+Results are summaries by default: identifying metadata, score, reasons, and a
+snippet. Read them to pick candidates, then `kb_query` those IDs for full
+bodies, or pass `fields: "full"` when you genuinely need every body. Extract
+the relevant existing constraints and decisions from the response before
+planning a behavior change; a search receipt is not comprehension.
+
 ## Discovery to Validation Sequence
 
 The canonical workflow for any KB operation follows this pattern:
 
-1. **Discover**: `kb_search` with focused probes
+1. **Discover**: `kb_search` with focused probes; 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

package/src/public/symbol-granularity.generated.ts

@@ -8,34 +8,67 @@
  */
 // implements REQ-core-extractors
 
-export const ALLOWED_GRANULARITY_REASONS = ["config-artifact","module-level-behavior","extractor-miss","legacy-link","test-suite"] as const;
+export const ALLOWED_GRANULARITY_REASONS = [
+  "config-artifact",
+  "module-level-behavior",
+  "extractor-miss",
+  "legacy-link",
+  "test-suite",
+] as const;
 
-export type GranularityReason =
-  (typeof ALLOWED_GRANULARITY_REASONS)[number];
+export type GranularityReason = (typeof ALLOWED_GRANULARITY_REASONS)[number];
 
-export const COARSE_GRANULARITY_REASONS = ["config-artifact","module-level-behavior","extractor-miss","test-suite"] as const;
+export const COARSE_GRANULARITY_REASONS = [
+  "config-artifact",
+  "module-level-behavior",
+  "extractor-miss",
+  "test-suite",
+] as const;
 
 export type CoarseGranularityReason =
   (typeof COARSE_GRANULARITY_REASONS)[number];
 
-export const SYMBOL_ROLES = ["behavioral","structural","type-shape","config","module","unknown"] as const;
+export const SYMBOL_ROLES = [
+  "behavioral",
+  "structural",
+  "type-shape",
+  "config",
+  "module",
+  "unknown",
+] as const;
 
 export type SymbolRole = (typeof SYMBOL_ROLES)[number];
 
-export const ROLE_INFERENCE: Readonly<
-  Record<string, SymbolRole>
-> = {"function":"behavioral","class":"behavioral","method":"behavioral","property":"behavioral","accessor":"behavioral","interface":"type-shape","type":"type-shape","enum":"type-shape","variable":"unknown","unknown":"unknown"};
+export const ROLE_INFERENCE: Readonly<Record<string, SymbolRole>> = {
+  function: "behavioral",
+  class: "behavioral",
+  method: "behavioral",
+  property: "behavioral",
+  accessor: "behavioral",
+  interface: "type-shape",
+  type: "type-shape",
+  enum: "type-shape",
+  variable: "unknown",
+  unknown: "unknown",
+};
 
-export const TRACEABILITY_RELATIONSHIP_TYPES = ["implements","covered_by","executable_for"] as const;
+export const TRACEABILITY_RELATIONSHIP_TYPES = [
+  "implements",
+  "covered_by",
+  "executable_for",
+] as const;
 
 export type TraceabilityRelationshipType =
   (typeof TRACEABILITY_RELATIONSHIP_TYPES)[number];
 
 /** Comma-or list of every allowed granularity reason ("a, b, or c"). */
-export const ALLOWED_GRANULARITY_REASONS_PROSE = "config-artifact, module-level-behavior, extractor-miss, legacy-link, or test-suite";
+export const ALLOWED_GRANULARITY_REASONS_PROSE =
+  "config-artifact, module-level-behavior, extractor-miss, legacy-link, or test-suite";
 
 /** Comma-or list of the coarse granularity reasons ("a, b, or c"). */
-export const COARSE_GRANULARITY_REASONS_PROSE = "config-artifact, module-level-behavior, extractor-miss, or test-suite";
+export const COARSE_GRANULARITY_REASONS_PROSE =
+  "config-artifact, module-level-behavior, extractor-miss, or test-suite";
 
 /** Parenthesized coarse list for inline suggestions ("(a, b, c, d)"). */
-export const COARSE_GRANULARITY_REASONS_PARENTHESIZED = "(config-artifact, module-level-behavior, extractor-miss, test-suite)";
+export const COARSE_GRANULARITY_REASONS_PARENTHESIZED =
+  "(config-artifact, module-level-behavior, extractor-miss, test-suite)";

package/src/public/symbol-granularity.ts

@@ -4,12 +4,12 @@ import {
   COARSE_GRANULARITY_REASONS,
   COARSE_GRANULARITY_REASONS_PARENTHESIZED,
   COARSE_GRANULARITY_REASONS_PROSE,
-  ROLE_INFERENCE,
-  SYMBOL_ROLES,
-  TRACEABILITY_RELATIONSHIP_TYPES,
   type CoarseGranularityReason,
   type GranularityReason,
+  ROLE_INFERENCE,
+  SYMBOL_ROLES,
   type SymbolRole,
+  TRACEABILITY_RELATIONSHIP_TYPES,
   type TraceabilityRelationshipType,
 } from "./symbol-granularity.generated.js";
 

package/src/public/telemetry-acceptance.ts

@@ -363,11 +363,30 @@ function advisorBeforeRequirementWriteMetric(
   };
 }
 
+function sourceLookupMessage(
+  zeroResults: number,
+  lookups: number,
+  unobservable: number,
+): string {
+  const unreadable =
+    unobservable > 0
+      ? `${unobservable} source-linked lookups recorded no readable result count.`
+      : "";
+  if (lookups === 0) {
+    return (
+      unreadable ||
+      "No source-linked query or search calls occurred in the evaluated window."
+    );
+  }
+  const observed = `${zeroResults}/${lookups} source-linked lookups returned zero results.`;
+  return unreadable ? `${observed} ${unreadable}` : observed;
+}
+
 function sourceLookupMetric(
   recent: readonly TimedEvent[],
   policy: TelemetryAcceptancePolicy,
 ): MutableMetric {
-  const lookups = recent.filter(({ event }) => {
+  const sourceLinked = recent.filter(({ event }) => {
     if (
       (event.tool !== "kb_query" && event.tool !== "kb_search") ||
       !eventSucceeded(event)
@@ -376,6 +395,14 @@ function sourceLookupMetric(
     }
     return typeof eventArgs(event).sourceFile === "string";
   });
+  // A row whose count could not be read is unobservable, not a hit.  Counting
+  // it as a non-zero result would let a broken logger report a healthy rate.
+  const lookups = sourceLinked.filter(
+    ({ event }) =>
+      typeof event.result_count === "number" ||
+      typeof event.zero_results === "boolean",
+  );
+  const unobservable = sourceLinked.length - lookups.length;
   const zeroResults = lookups.filter(
     ({ event }) => event.zero_results === true || event.result_count === 0,
   );
@@ -387,7 +414,10 @@ function sourceLookupMetric(
   }
   return {
     id: "source_lookup_zero_result_rate",
-    status: thresholdStatus(actual, "<=", policy.sourceLookupZeroResultMaximum),
+    status:
+      lookups.length === 0 && unobservable > 0
+        ? "insufficient_evidence"
+        : thresholdStatus(actual, "<=", policy.sourceLookupZeroResultMaximum),
     numerator: zeroResults.length,
     denominator: lookups.length,
     ...(actual !== undefined ? { rate: actual } : {}),
@@ -395,10 +425,11 @@ function sourceLookupMetric(
       operator: "<=",
       value: policy.sourceLookupZeroResultMaximum,
     },
-    message:
-      lookups.length === 0
-        ? "No source-linked query or search calls occurred in the evaluated window."
-        : `${zeroResults.length}/${lookups.length} source-linked lookups returned zero results.`,
+    message: sourceLookupMessage(
+      zeroResults.length,
+      lookups.length,
+      unobservable,
+    ),
     evidence: {
       zeroResultSourceFiles: [...sourceCounts.entries()]
         .sort(

package/src/schemas/entity.schema.json

@@ -1173,6 +1173,28 @@
         "type": "string"
       }
     },
+    "argument_constants": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "array",
+        "minItems": 1,
+        "uniqueItems": true,
+        "items": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "argument_aliases": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
     "rule_ir": {
       "$ref": "#/$defs/logicRule"
     },
@@ -1373,6 +1395,16 @@
                 "predicate_args"
               ]
             },
+            {
+              "required": [
+                "argument_constants"
+              ]
+            },
+            {
+              "required": [
+                "argument_aliases"
+              ]
+            },
             {
               "required": [
                 "rule_ir"

package/src/schemas/relationship.schema.json

@@ -22,6 +22,7 @@
         "publishes",
         "consumes",
         "supersedes",
+        "restates",
         "relates_to"
       ]
     },