kibi-cli 2.1.0 → 2.2.0

package/dist/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/dist/public/telemetry-acceptance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"telemetry-acceptance.d.ts","sourceRoot":"","sources":["../../src/public/telemetry-acceptance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAEV,yBAAyB,EACzB,yBAAyB,EAGzB,qBAAqB,EACrB,mBAAmB,EACpB,MAAM,iCAAiC,CAAC;AAEzC,YAAY,EACV,yBAAyB,EACzB,yBAAyB,EACzB,yBAAyB,EACzB,yBAAyB,EACzB,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,iCAAiC,CAAC;AAEzC,eAAO,MAAM,4BAA4B,EACvC,8BAAuC,CAAC;AAE1C,eAAO,MAAM,mCAAmC;;;;;;;;;;;;CAYF,CAAC;AAgB/C,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,GACf,mBAAmB,EAAE,CAsBvB;AA0DD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,QAAQ,EAAE,IAAI,GAAG,IAAI,GAAG,GAAG,EAC3B,QAAQ,EAAE,MAAM,GACf,qBAAqB,CAKvB;AA2bD,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,SAAS,mBAAmB,EAAE,EACtC,GAAG,GAAE,IAAiB,EACtB,MAAM,GAAE,yBAA+D,GACtE,yBAAyB,CA6D3B;AA+DD,wBAAgB,oCAAoC,CAClD,MAAM,EAAE,yBAAyB,GAChC,SAAS,iBAAiB,EAAE,CA+E9B"}
+{"version":3,"file":"telemetry-acceptance.d.ts","sourceRoot":"","sources":["../../src/public/telemetry-acceptance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAEV,yBAAyB,EACzB,yBAAyB,EAGzB,qBAAqB,EACrB,mBAAmB,EACpB,MAAM,iCAAiC,CAAC;AAEzC,YAAY,EACV,yBAAyB,EACzB,yBAAyB,EACzB,yBAAyB,EACzB,yBAAyB,EACzB,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,iCAAiC,CAAC;AAEzC,eAAO,MAAM,4BAA4B,EACvC,8BAAuC,CAAC;AAE1C,eAAO,MAAM,mCAAmC;;;;;;;;;;;;CAYF,CAAC;AAgB/C,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,GACf,mBAAmB,EAAE,CAsBvB;AA0DD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,QAAQ,EAAE,IAAI,GAAG,IAAI,GAAG,GAAG,EAC3B,QAAQ,EAAE,MAAM,GACf,qBAAqB,CAKvB;AA0dD,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,SAAS,mBAAmB,EAAE,EACtC,GAAG,GAAE,IAAiB,EACtB,MAAM,GAAE,yBAA+D,GACtE,yBAAyB,CA6D3B;AA+DD,wBAAgB,oCAAoC,CAClD,MAAM,EAAE,yBAAyB,GAChC,SAAS,iBAAiB,EAAE,CA+E9B"}

package/dist/public/telemetry-acceptance.js

@@ -251,14 +251,30 @@ function advisorBeforeRequirementWriteMetric(all, recentStart, policy) {
         },
     };
 }
+function sourceLookupMessage(zeroResults, lookups, unobservable) {
+    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, policy) {
-    const lookups = recent.filter(({ event }) => {
+    const sourceLinked = recent.filter(({ event }) => {
         if ((event.tool !== "kb_query" && event.tool !== "kb_search") ||
             !eventSucceeded(event)) {
             return false;
         }
         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);
     const actual = rate(zeroResults.length, lookups.length);
     const sourceCounts = new Map();
@@ -268,7 +284,9 @@ function sourceLookupMetric(recent, policy) {
     }
     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 } : {}),
@@ -276,9 +294,7 @@ function sourceLookupMetric(recent, policy) {
             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(([leftFile, leftCount], [rightFile, rightCount]) => rightCount - leftCount || leftFile.localeCompare(rightFile))

package/dist/relationships/shards.d.ts

@@ -50,6 +50,12 @@ export type RemovedRelationshipRecords = Readonly<{
  * Remove exact legacy-shard relationships using an atomic temp-file rename.
  * The caller is responsible for retracting the compiled RDF edge afterwards.
  */
+/**
+ * A shard's YAML without the selected relationships. The sequence is patched in
+ * place so comments, ordering, and unrelated records survive; callers that must
+ * approve the bytes before writing (deletion plans) render without writing.
+ */
+export declare function renderShardWithout(text: string, selectors: readonly RelationshipSelector[], shardPath: string): string;
 export declare function removeRelationshipsFromShards(kbRoot: string, selectors: readonly RelationshipSelector[]): RemovedRelationshipRecords[];
 /**
  * Appends a relationship to the appropriate shard.

package/dist/relationships/shards.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shards.d.ts","sourceRoot":"","sources":["../../src/relationships/shards.ts"],"names":[],"mappings":"AAwBA;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGzE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAsFjE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kBAAkB,EAAE,GAC5B,IAAI,CAoBN;AAwBD,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC,CAAC;AAEH,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC;IAChD,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC,CAAC;AAEH;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,oBAAoB,EAAE,GACzC,0BAA0B,EAAE,CAwD9B;AAqCD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,IAAI,CAAC,kBAAkB,EAAE,IAAI,CAAC,GAC3C;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAwCzC;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAUnD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAUlE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,kBAAkB,EAAE,EAC7B,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAC1B,kBAAkB,EAAE,CAKtB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,MAAM,CAMR;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAE1B,QAAQ,EAAE,kBAAkB,EAAE,EAC9B,QAAQ,EAAE,kBAAkB,EAAE,GAC7B,kBAAkB,EAAE,CAgCtB"}
+{"version":3,"file":"shards.d.ts","sourceRoot":"","sources":["../../src/relationships/shards.ts"],"names":[],"mappings":"AAwBA;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGzE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAsFjE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kBAAkB,EAAE,GAC5B,IAAI,CAoBN;AAwBD,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC,CAAC;AAEH,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC;IAChD,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC,CAAC;AAEH;;;GAGG;AACH;;;;GAIG;AAEH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,SAAS,oBAAoB,EAAE,EAC1C,SAAS,EAAE,MAAM,GAChB,MAAM,CA2BR;AAED,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,oBAAoB,EAAE,GACzC,0BAA0B,EAAE,CAwC9B;AAqCD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,IAAI,CAAC,kBAAkB,EAAE,IAAI,CAAC,GAC3C;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAwCzC;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAUnD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAUlE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,kBAAkB,EAAE,EAC7B,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAC1B,kBAAkB,EAAE,CAKtB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,MAAM,CAMR;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAE1B,QAAQ,EAAE,kBAAkB,EAAE,EAC9B,QAAQ,EAAE,kBAAkB,EAAE,GAC7B,kBAAkB,EAAE,CAgCtB"}

package/dist/relationships/shards.js

@@ -163,6 +163,31 @@ function atomicWriteText(targetPath, body) {
  * Remove exact legacy-shard relationships using an atomic temp-file rename.
  * The caller is responsible for retracting the compiled RDF edge afterwards.
  */
+/**
+ * A shard's YAML without the selected relationships. The sequence is patched in
+ * place so comments, ordering, and unrelated records survive; callers that must
+ * approve the bytes before writing (deletion plans) render without writing.
+ */
+// implements REQ-kibi-operation-interface-parity
+export function renderShardWithout(text, selectors, shardPath) {
+    const wanted = new Set(selectors.map((selector) => `${selector.type}\0${selector.from}\0${selector.to}`));
+    const document = parseDocument(text);
+    const sequence = document.get("relationships", true);
+    if (!sequence || typeof sequence !== "object" || !("items" in sequence)) {
+        throw new Error(`Invalid shard file: missing 'relationships' array at ${shardPath}`);
+    }
+    const items = sequence.items;
+    for (let index = items.length - 1; index >= 0; index -= 1) {
+        const item = items[index];
+        if (!item || typeof item !== "object" || !("get" in item))
+            continue;
+        const get = item.get.bind(item);
+        if (wanted.has(`${String(get("type"))}\0${String(get("from"))}\0${String(get("to"))}`)) {
+            document.deleteIn(["relationships", index]);
+        }
+    }
+    return document.toString();
+}
 export function removeRelationshipsFromShards(kbRoot, selectors) {
     const wanted = new Set(selectors.map((selector) => `${selector.type}\0${selector.from}\0${selector.to}`));
     const removed = new Map();
@@ -171,25 +196,7 @@ export function removeRelationshipsFromShards(kbRoot, selectors) {
         const matching = records.filter((record) => wanted.has(`${record.type}\0${record.from}\0${record.to}`));
         if (matching.length === 0)
             continue;
-        // Patch the YAML sequence in place so comments, ordering, and unrelated
-        // records survive a relationship deletion. The compiled store is never
-        // the mutation target; this shard remains the canonical source artifact.
-        const document = parseDocument(fs.readFileSync(shardPath, "utf8"));
-        const sequence = document.get("relationships", true);
-        if (!sequence || typeof sequence !== "object" || !("items" in sequence)) {
-            throw new Error(`Invalid shard file: missing 'relationships' array at ${shardPath}`);
-        }
-        const items = sequence.items;
-        for (let index = items.length - 1; index >= 0; index -= 1) {
-            const item = items[index];
-            if (!item || typeof item !== "object" || !("get" in item))
-                continue;
-            const get = item.get.bind(item);
-            if (wanted.has(`${String(get("type"))}\0${String(get("from"))}\0${String(get("to"))}`)) {
-                document.deleteIn(["relationships", index]);
-            }
-        }
-        atomicWriteText(shardPath, document.toString());
+        atomicWriteText(shardPath, renderShardWithout(fs.readFileSync(shardPath, "utf8"), selectors, shardPath));
         for (const record of matching) {
             const key = `${record.type}\0${record.from}\0${record.to}`;
             const entry = removed.get(key) ?? { paths: [], sources: [] };

package/dist/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/dist/traceability/staged-diagnostics.d.ts

@@ -1,6 +1,6 @@
 import type { QualityDiagnostic } from "../public/impact/types.js";
 import { type KibiImpactEvidence } from "./evidence-model.js";
-export type KibiImpactDiagnosticId = "kibi_impact_evidence_missing" | "symbols_manifest_stale" | "symbol_granularity_violation" | "symbol_semantic_review_needed" | "multi_requirement_symbol_review" | "duplicate_symbol_coordinate_review" | "component_mixed_purpose_review" | "broad_requirement_review" | "requirement_status_review" | "strict_fact_modeling_review" | "logical_coverage_review" | "kibi_impact_override_missing_rationale";
+export type KibiImpactDiagnosticId = "kibi_impact_evidence_missing" | "symbols_manifest_stale" | "symbol_granularity_violation" | "symbol_semantic_review_needed" | "multi_requirement_symbol_review" | "duplicate_symbol_coordinate_review" | "component_mixed_purpose_review" | "broad_requirement_review" | "requirement_status_review" | "strict_fact_modeling_review" | "logical_coverage_review" | "kibi_impact_override_missing_rationale" | "entity_id_style_review";
 export interface KibiImpactDiagnostic extends QualityDiagnostic {
     /** Stable staged-enforcement diagnostic identifier. */
     id: KibiImpactDiagnosticId;

package/dist/traceability/staged-diagnostics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"staged-diagnostics.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-diagnostics.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAGL,KAAK,kBAAkB,EAKxB,MAAM,qBAAqB,CAAC;AAQ7B,MAAM,MAAM,sBAAsB,GAC9B,8BAA8B,GAC9B,wBAAwB,GACxB,8BAA8B,GAC9B,+BAA+B,GAC/B,iCAAiC,GACjC,oCAAoC,GACpC,gCAAgC,GAChC,0BAA0B,GAC1B,2BAA2B,GAC3B,6BAA6B,GAC7B,yBAAyB,GACzB,wCAAwC,CAAC;AAE7C,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D,uDAAuD;IACvD,EAAE,EAAE,sBAAsB,CAAC;IAC3B,QAAQ,EAAE,iBAAiB,CAAC,UAAU,CAAC,CAAC;IACxC,iEAAiE;IACjE,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,gDAAgD;IAChD,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAwID,wBAAgB,wCAAwC,CACtD,QAAQ,EAAE,kBAAkB,GAC3B,oBAAoB,CAoBtB;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,kBAAkB,EAC5B,mBAAmB,GAAE,MAAmC,GACvD,oBAAoB,EAAE,CAiDxB"}
+{"version":3,"file":"staged-diagnostics.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-diagnostics.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAGL,KAAK,kBAAkB,EAKxB,MAAM,qBAAqB,CAAC;AAQ7B,MAAM,MAAM,sBAAsB,GAC9B,8BAA8B,GAC9B,wBAAwB,GACxB,8BAA8B,GAC9B,+BAA+B,GAC/B,iCAAiC,GACjC,oCAAoC,GACpC,gCAAgC,GAChC,0BAA0B,GAC1B,2BAA2B,GAC3B,6BAA6B,GAC7B,yBAAyB,GACzB,wCAAwC,GACxC,wBAAwB,CAAC;AAE7B,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D,uDAAuD;IACvD,EAAE,EAAE,sBAAsB,CAAC;IAC3B,QAAQ,EAAE,iBAAiB,CAAC,UAAU,CAAC,CAAC;IACxC,iEAAiE;IACjE,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,gDAAgD;IAChD,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAwID,wBAAgB,wCAAwC,CACtD,QAAQ,EAAE,kBAAkB,GAC3B,oBAAoB,CAoBtB;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,kBAAkB,EAC5B,mBAAmB,GAAE,MAAmC,GACvD,oBAAoB,EAAE,CAiDxB"}

package/dist/traceability/staged-entity-id-style.d.ts

@@ -0,0 +1,12 @@
+import type { StagedFile } from "./git-staged.js";
+import type { KibiImpactDiagnostic } from "./staged-diagnostics.js";
+/**
+ * Naming-style review for entity Markdown that this commit introduces.
+ *
+ * Only added or renamed files are evaluated: a staged edit to a committed
+ * legacy entity such as `REQ-003.md` is never reported, so the legacy numbered
+ * lanes stay grandfathered without a cutoff date or history lookup. The
+ * diagnostics are advisory and never block a commit.
+ */
+export declare function createStagedEntityIdStyleDiagnostics(stagedFiles: readonly StagedFile[]): KibiImpactDiagnostic[];
+//# sourceMappingURL=staged-entity-id-style.d.ts.map

package/dist/traceability/staged-entity-id-style.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staged-entity-id-style.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-entity-id-style.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAEpE;;;;;;;GAOG;AAEH,wBAAgB,oCAAoC,CAClD,WAAW,EAAE,SAAS,UAAU,EAAE,GACjC,oBAAoB,EAAE,CAuBxB"}

package/dist/traceability/staged-entity-id-style.js

@@ -0,0 +1,68 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+import { extractFromMarkdownString } from "../extractors/markdown.js";
+import { entityIdStyleIssues } from "../utils/entity-id-style.js";
+import { isEntityLanePath } from "../utils/kb-paths.js";
+/**
+ * Naming-style review for entity Markdown that this commit introduces.
+ *
+ * Only added or renamed files are evaluated: a staged edit to a committed
+ * legacy entity such as `REQ-003.md` is never reported, so the legacy numbered
+ * lanes stay grandfathered without a cutoff date or history lookup. The
+ * diagnostics are advisory and never block a commit.
+ */
+// implements REQ-kibi-entity-id-style
+export function createStagedEntityIdStyleDiagnostics(stagedFiles) {
+    const diagnostics = [];
+    for (const file of stagedFiles) {
+        if (file.status !== "A" && file.status !== "R")
+            continue;
+        if (!file.path.endsWith(".md") || !isEntityLanePath(file.path))
+            continue;
+        const id = readEntityId(file);
+        if (id === undefined)
+            continue;
+        for (const issue of entityIdStyleIssues({ id, sourcePath: file.path })) {
+            diagnostics.push({
+                id: "entity_id_style_review",
+                severity: "warning",
+                blocking: false,
+                category: "naming",
+                entityId: id,
+                source: file.path,
+                files: [file.path],
+                docs: ["docs/entity-schema.md"],
+                message: issue.message,
+                suggestion: issue.suggestion,
+            });
+        }
+    }
+    return diagnostics;
+}
+function readEntityId(file) {
+    if (file.content === undefined)
+        return undefined;
+    try {
+        const id = extractFromMarkdownString(file.content, file.path).entity.id;
+        return typeof id === "string" && id.trim() !== "" ? id.trim() : undefined;
+    }
+    catch {
+        // Frontmatter errors are reported by staged Markdown validation.
+        return undefined;
+    }
+}

package/dist/traceability/temp-kb.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"temp-kb.d.ts","sourceRoot":"","sources":["../../src/traceability/temp-kb.ts"],"names":[],"mappings":"AAMA,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,OAAO,CAET;AACD,OAAO,KAAK,EAGV,gBAAgB,EACjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,aAAa,CAAC;CACvB;AAMD;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CASvC;AAQD;;;GAGG;AACH,wBAAgB,iBAAiB,CAE/B,OAAO,EAAE,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,KAAK,CAAA;CAAE,KAAK,aAAa,GACpE,IAAI,CAEN;AAmQD,iBAAe,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB/D;AAED,OAAO,EAAE,cAAc,EAAE,CAAC;AAG1B,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,GAC1B,OAAO,CAAC,IAAI,CAAC,CA2Bf;AAED,wBAAsB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CA6C7E;AAGD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,MAAM,CAkBrE;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BlE"}
+{"version":3,"file":"temp-kb.d.ts","sourceRoot":"","sources":["../../src/traceability/temp-kb.ts"],"names":[],"mappings":"AAMA,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,OAAO,CAET;AACD,OAAO,KAAK,EAGV,gBAAgB,EACjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,aAAa,CAAC;CACvB;AAMD;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CASvC;AAQD;;;GAGG;AACH,wBAAgB,iBAAiB,CAE/B,OAAO,EAAE,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,KAAK,CAAA;CAAE,KAAK,aAAa,GACpE,IAAI,CAEN;AA4QD,iBAAe,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB/D;AAED,OAAO,EAAE,cAAc,EAAE,CAAC;AAG1B,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,GAC1B,OAAO,CAAC,IAAI,CAAC,CA2Bf;AAED,wBAAsB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CA6C7E;AAGD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,MAAM,CAkBrE;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BlE"}

package/dist/traceability/temp-kb.js

@@ -107,6 +107,14 @@ function serializeTypedFactFields(entity) {
     if (ruleIr !== undefined && ruleIr !== null) {
         fields.push(`rule_ir=${toPrologString(JSON.stringify(ruleIr))}`);
     }
+    // Predicate-schema vocabularies are objects; like rule_ir they travel as
+    // JSON strings and are decoded again at the public boundary.
+    for (const field of ["argument_constants", "argument_aliases"]) {
+        const value = getEntityField(entity, field);
+        if (value !== undefined && value !== null) {
+            fields.push(`${field}=${toPrologString(JSON.stringify(value))}`);
+        }
+    }
     for (const field of FACT_ATOM_FIELDS) {
         const value = getEntityField(entity, field);
         if (value !== undefined && value !== null) {

package/dist/traceability/validate.js

@@ -153,7 +153,7 @@ export function formatViolations(violations) {
         const loc = `${v.file}:${v.line}`;
         const name = `${v.name}()`;
         // Suggest adding requirement links with role-specific guidance
-        const suggestion = "Add ownership: implements: REQ-001 (production code), use covered_by for production coverage, or executable_for for executable test code";
+        const suggestion = "Add ownership: implements: REQ-<area>-<behavior> (production code), use covered_by for production coverage, or executable_for for executable test code";
         lines.push(`${loc}  ${name}  -> ${suggestion}`);
     }
     return lines.join("\n");

package/dist/types/entities.d.ts

@@ -39,6 +39,8 @@ export interface FactFields {
     argument_names?: string[];
     argument_types?: string[];
     argument_descriptions?: string[];
+    argument_constants?: Record<string, string[]>;
+    argument_aliases?: Record<string, Record<string, string>>;
     aliases?: string[];
     examples?: string[];
     predicate_args?: string[];

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

@@ -1 +1 @@
-{"version":3,"file":"entities.d.ts","sourceRoot":"","sources":["../../src/types/entities.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE/D,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;IACnD,cAAc,CAAC,EAAE,aAAa,CAAC;IAC/B,cAAc,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IACzC,cAAc,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;CAC1C;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"}
+{"version":3,"file":"entities.d.ts","sourceRoot":"","sources":["../../src/types/entities.ts"],"names":[],"mappings":"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"}

package/dist/types/relationships.d.ts

@@ -1,5 +1,5 @@
 export interface BaseRelationship {
-    type: "depends_on" | "specified_by" | "verified_by" | "validates" | "implements" | "covered_by" | "executable_for" | "constrained_by" | "constrains" | "requires_property" | "requires_predicate" | "requires_rule" | "guards" | "publishes" | "consumes" | "supersedes" | "relates_to";
+    type: "depends_on" | "specified_by" | "verified_by" | "validates" | "implements" | "covered_by" | "executable_for" | "constrained_by" | "constrains" | "requires_property" | "requires_predicate" | "requires_rule" | "guards" | "publishes" | "consumes" | "supersedes" | "restates" | "relates_to";
     from: string;
     to: string;
     created_at?: string;

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

@@ -1 +1 @@
-{"version":3,"file":"relationships.d.ts","sourceRoot":"","sources":["../../src/types/relationships.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EACA,YAAY,GACZ,cAAc,GACd,aAAa,GACb,WAAW,GACX,YAAY,GACZ,YAAY,GACZ,gBAAgB,GAChB,gBAAgB,GAChB,YAAY,GACZ,mBAAmB,GACnB,oBAAoB,GACpB,eAAe,GACf,QAAQ,GACR,WAAW,GACX,UAAU,GACV,YAAY,GACZ,YAAY,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,eAAe,gBAAgB,CAAC"}
+{"version":3,"file":"relationships.d.ts","sourceRoot":"","sources":["../../src/types/relationships.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EACA,YAAY,GACZ,cAAc,GACd,aAAa,GACb,WAAW,GACX,YAAY,GACZ,YAAY,GACZ,gBAAgB,GAChB,gBAAgB,GAChB,YAAY,GACZ,mBAAmB,GACnB,oBAAoB,GACpB,eAAe,GACf,QAAQ,GACR,WAAW,GACX,UAAU,GACV,YAAY,GACZ,UAAU,GACV,YAAY,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,eAAe,gBAAgB,CAAC"}

package/dist/utils/entity-id-style.d.ts

@@ -0,0 +1,27 @@
+/** Purely numeric entity ID such as `REQ-001` or `ADR-12`. */
+export declare const NUMERIC_ENTITY_ID_PATTERN: RegExp;
+export type EntityIdStyleIssue = Readonly<{
+    code: "numeric_id" | "stem_mismatch";
+    message: string;
+    suggestion: string;
+}>;
+export declare function isNumericEntityId(id: string): boolean;
+/**
+ * Filename stem for an authored Markdown source, or undefined for non-Markdown
+ * sources (symbol manifests, code files, runtime `mcp://` provenance).
+ */
+export declare function markdownSourceStem(sourcePath: string | undefined): string | undefined;
+/**
+ * Style issues for one newly created entity. Callers decide whether the entity
+ * is new; this function never inspects the KB.
+ */
+export declare function entityIdStyleIssues(input: {
+    readonly id: string;
+    readonly sourcePath?: string | undefined;
+}): EntityIdStyleIssue[];
+/** Plain-text warnings for mutation receipts. */
+export declare function entityIdStyleWarnings(input: {
+    readonly id: string;
+    readonly sourcePath?: string | undefined;
+}): string[];
+//# sourceMappingURL=entity-id-style.d.ts.map

package/dist/utils/entity-id-style.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-id-style.d.ts","sourceRoot":"","sources":["../../src/utils/entity-id-style.ts"],"names":[],"mappings":"AAiCA,8DAA8D;AAE9D,eAAO,MAAM,yBAAyB,QAAiB,CAAC;AAGxD,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,IAAI,EAAE,YAAY,GAAG,eAAe,CAAC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC,CAAC;AAGH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;;GAGG;AAEH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,MAAM,GAAG,SAAS,CAOpB;AAED;;;GAGG;AAEH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE;IACzC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C,GAAG,kBAAkB,EAAE,CAoBvB;AAED,iDAAiD;AAEjD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IAC3C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C,GAAG,MAAM,EAAE,CAIX"}

package/dist/utils/entity-id-style.js

@@ -0,0 +1,81 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+/**
+ * Entity naming style (`entity-id-style`).
+ *
+ * Entities are named by what they govern (`REQ-cli-gc`), never by "the next
+ * number". The compiled KB cannot tell a legacy numbered entity from a new one
+ * (`created_at` is stamped at sync time when frontmatter omits it), so purely
+ * numeric IDs are reported only at creation boundaries: a `kb_upsert` that
+ * creates the entity, and staged added/renamed entity Markdown. Committed
+ * legacy entities such as `REQ-003` are therefore never flagged. The Prolog
+ * half of the rule (`check_entity_id_style/1`) reports filename-stem/`id`
+ * mismatches over the whole KB.
+ */
+import * as path from "node:path";
+/** Purely numeric entity ID such as `REQ-001` or `ADR-12`. */
+// implements REQ-kibi-entity-id-style
+export const NUMERIC_ENTITY_ID_PATTERN = /^[A-Z]+-\d+$/;
+// implements REQ-kibi-entity-id-style
+export function isNumericEntityId(id) {
+    return NUMERIC_ENTITY_ID_PATTERN.test(id.trim());
+}
+/**
+ * Filename stem for an authored Markdown source, or undefined for non-Markdown
+ * sources (symbol manifests, code files, runtime `mcp://` provenance).
+ */
+// implements REQ-kibi-entity-id-style
+export function markdownSourceStem(sourcePath) {
+    if (sourcePath === undefined)
+        return undefined;
+    const normalized = sourcePath.trim().replaceAll("\\", "/");
+    if (!normalized.endsWith(".md") || normalized.includes("://")) {
+        return undefined;
+    }
+    return path.posix.basename(normalized, ".md");
+}
+/**
+ * Style issues for one newly created entity. Callers decide whether the entity
+ * is new; this function never inspects the KB.
+ */
+// implements REQ-kibi-entity-id-style
+export function entityIdStyleIssues(input) {
+    const id = input.id.trim();
+    const issues = [];
+    if (isNumericEntityId(id)) {
+        issues.push({
+            code: "numeric_id",
+            message: `Entity ID ${id} is a sequence number; parallel branches pick the same next number and collide.`,
+            suggestion: "Name the entity by what it governs: <TYPE>-<area>-<behavior> in kebab-case (for example REQ-cli-gc). kb_search the area first and update or supersede an existing entity when one already covers the behavior.",
+        });
+    }
+    const stem = markdownSourceStem(input.sourcePath);
+    if (stem !== undefined && stem !== id) {
+        issues.push({
+            code: "stem_mismatch",
+            message: `Entity ID ${id} does not match its filename stem ${stem}.`,
+            suggestion: `Rename the file to ${id}.md or set frontmatter id: ${stem} so the file name and identity stay aligned.`,
+        });
+    }
+    return issues;
+}
+/** Plain-text warnings for mutation receipts. */
+// implements REQ-kibi-entity-id-style
+export function entityIdStyleWarnings(input) {
+    return entityIdStyleIssues(input).map((issue) => `entity-id-style: ${issue.message} ${issue.suggestion}`);
+}

package/dist/utils/git-repository-context.d.ts

@@ -0,0 +1,50 @@
+export interface GitRepositoryContext {
+    /** Root of the current working tree (the worktree, when linked). */
+    worktreeRoot: string;
+    /** Absolute Git directory of the current worktree. */
+    gitDir: string;
+    /** Absolute repository-common Git directory (shared across worktrees). */
+    commonGitDir: string;
+    /** Absolute hooks directory Git will actually execute (honors core.hooksPath). */
+    effectiveHooksDir: string;
+    isLinkedWorktree: boolean;
+    /**
+     * Primary checkout root, only when it can be validated as a real checkout
+     * (`git -C <candidate> rev-parse --show-toplevel` resolves to the
+     * candidate). Null for bare repositories, separate-git-dir layouts, and any
+     * candidate that is not itself a working tree.
+     */
+    primaryWorktreeRoot: string | null;
+    /** Raw core.hooksPath value when configured, else null. */
+    hooksPathConfig: string | null;
+    /** Config origin line (from --show-origin) for the configured hooksPath. */
+    hooksPathOrigin: string | null;
+}
+export type GitRepositoryResolution = {
+    status: "ok";
+    context: GitRepositoryContext;
+} | {
+    status: "not-a-repository";
+} | {
+    status: "git-unavailable";
+} | {
+    status: "git-refused";
+    /** First Git diagnostic (or fs detail) explaining the refusal. */
+    reason: string;
+} | {
+    status: "unsupported";
+    reason: string;
+};
+/**
+ * Resolve the effective Git repository context for `cwd` by asking Git
+ * instead of assuming `<cwd>/.git`. The result distinguishes "no repository"
+ * (callers may fall back to standalone-workspace behavior) from repositories
+ * Kibi must not touch (bare repositories) and directories where Git refused
+ * operationally (dubious ownership, unreadable `.git`, access failures) — the
+ * last must never be mistaken for "no repository", because that would send
+ * callers into standalone workspace writes.
+ *
+ * implements REQ-git-hook-effective-install
+ */
+export declare function resolveGitRepository(cwd?: string): GitRepositoryResolution;
+//# sourceMappingURL=git-repository-context.d.ts.map

package/dist/utils/git-repository-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-repository-context.d.ts","sourceRoot":"","sources":["../../src/utils/git-repository-context.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,oBAAoB;IACnC,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,2DAA2D;IAC3D,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,4EAA4E;IAC5E,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,MAAM,uBAAuB,GAC/B;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,oBAAoB,CAAA;CAAE,GAC/C;IAAE,MAAM,EAAE,kBAAkB,CAAA;CAAE,GAC9B;IAAE,MAAM,EAAE,iBAAiB,CAAA;CAAE,GAC7B;IACE,MAAM,EAAE,aAAa,CAAC;IACtB,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;CAChB,GACD;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAqH9C;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,GAAE,MAAsB,GAC1B,uBAAuB,CAmJzB"}