kibi-cli 0.11.1 → 0.12.0

package/src/public/skills/kibi-usage/resources/fact-lanes.md

@@ -24,6 +24,84 @@ value_type: int
 value_int: 3
 ```
 
+## Granular Facts for Coherence Checks
+
+Granular strict facts work best when each `property_value` represents one semantic claim about one `subject_key` and one `property_key`. This lets `domain-contradictions` compare current requirements that constrain the same subject and require incompatible values.
+
+### Role set conflict
+
+`REQ-ROLE-SET-2` and `REQ-ROLE-SET-3` are incoherent if both are current: they each define the exact allowed role set, but one allows two roles and the other allows three.
+
+```yaml
+subject:
+  id: FACT-USER-ROLES
+  title: User roles
+  status: active
+  fact_kind: subject
+  subject_key: user.roles
+
+property_values:
+  - id: FACT-USER-ROLES-ALLOWED-2
+    title: User and admin roles only
+    status: active
+    fact_kind: property_value
+    subject_key: user.roles
+    property_key: user.roles.allowed_set
+    operator: eq
+    value_type: list
+    value_json: '["user", "admin"]'
+  - id: FACT-USER-ROLES-ALLOWED-3
+    title: User, admin, and superadmin roles
+    status: active
+    fact_kind: property_value
+    subject_key: user.roles
+    property_key: user.roles.allowed_set
+    operator: eq
+    value_type: list
+    value_json: '["user", "admin", "superadmin"]'
+
+relationships:
+  - { type: constrains, from: REQ-ROLE-SET-2, to: FACT-USER-ROLES }
+  - { type: requires_property, from: REQ-ROLE-SET-2, to: FACT-USER-ROLES-ALLOWED-2 }
+  - { type: constrains, from: REQ-ROLE-SET-3, to: FACT-USER-ROLES }
+  - { type: requires_property, from: REQ-ROLE-SET-3, to: FACT-USER-ROLES-ALLOWED-3 }
+```
+
+### Permission actor conflict
+
+`REQ-ADMIN-CAN-MANAGE-BILLING` and `REQ-ONLY-SUPERADMIN-MANAGES-BILLING` conflict when both define the exact allowed actor for the same permission.
+
+```yaml
+subject:
+  id: FACT-BILLING-MANAGE
+  title: Billing management permission
+  status: active
+  fact_kind: subject
+  subject_key: billing.manage
+
+property_values:
+  - id: FACT-BILLING-MANAGE-ACTOR-ADMIN
+    title: Admin can manage billing
+    status: active
+    fact_kind: property_value
+    subject_key: billing.manage
+    property_key: billing.manage.allowed_actor
+    operator: eq
+    value_type: string
+    value_string: admin
+  - id: FACT-BILLING-MANAGE-ACTOR-SUPERADMIN
+    title: Only superadmin can manage billing
+    status: active
+    fact_kind: property_value
+    subject_key: billing.manage
+    property_key: billing.manage.allowed_actor
+    operator: eq
+    value_type: string
+    value_string: superadmin
+```
+
+When a contradiction is intentional evolution rather than a real conflict, link the replaced requirement to the replacement requirement with `supersedes`.
+
 ## Context Lane (Non-Blocking)
 
 ### fact_kind: observation

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

@@ -26,10 +26,3 @@ The canonical workflow for any KB operation follows this pattern:
 3. kb_upsert to add missing relationship rows (sequential)
 4. kb_check with rules: ["no-dangling-refs", "symbol-traceability"]
 ```
-
-## Before Risky Work
-```
-1. /brief-kibi or kb_briefing_generate for citation-backed briefing
-2. Inspect briefingState; proceed only if ready
-3. Use constraints, regressionRisks, and cited entities from the briefing
-```

package/src/public/skills.ts

@@ -84,14 +84,17 @@ export class SkillOversizeError extends Error {
   readonly actualBytes: number;
 
   constructor(pathLike: string, maxBytes: number, actualBytes: number) {
-    super(`Skill file exceeds ${maxBytes} bytes: ${pathLike} (${actualBytes} bytes)`);
+    super(
+      `Skill file exceeds ${maxBytes} bytes: ${pathLike} (${actualBytes} bytes)`,
+    );
     this.name = "SkillOversizeError";
     this.maxBytes = maxBytes;
     this.actualBytes = actualBytes;
   }
 }
 
-export function listBundledSkills(): SkillManifest[] { // implements REQ-001
+export function listBundledSkills(): SkillManifest[] {
+  // implements REQ-001
   if (!existsSync(bundledSkillsDir)) {
     return [];
   }
@@ -104,7 +107,8 @@ export function listBundledSkills(): SkillManifest[] { // implements REQ-001
     .sort((left, right) => left.id.localeCompare(right.id));
 }
 
-export function loadBundledSkill(id: string): SkillBundle { // implements REQ-001
+export function loadBundledSkill(id: string): SkillBundle {
+  // implements REQ-001
   const rootDir = findBundledSkillRoot(id);
   if (!rootDir) {
     throw new SkillNotFoundError(id);
@@ -116,7 +120,8 @@ export function loadBundledSkill(id: string): SkillBundle { // implements REQ-00
 export function readBundledSkillResource(
   id: string,
   resourcePath: string,
-): string { // implements REQ-001
+): string {
+  // implements REQ-001
   const bundle = loadBundledSkill(id);
   const declaredResource = normalizeResourcePath(resourcePath);
 
@@ -146,14 +151,18 @@ export function readBundledSkillResource(
   return readFileSync(candidatePath, "utf8");
 }
 
-export function validateSkillBundle(
-  pathLike: string,
-): { valid: boolean; errors: SkillValidationError[] } { // implements REQ-001
+export function validateSkillBundle(pathLike: string): {
+  valid: boolean;
+  errors: SkillValidationError[];
+} {
+  // implements REQ-001
   const skillFilePath = resolveSkillFilePath(pathLike);
   const errors: SkillValidationError[] = [];
 
   if (!existsSync(skillFilePath)) {
-    errors.push(new SkillValidationError("SKILL.md", `Missing ${SKILL_FILE_NAME}`));
+    errors.push(
+      new SkillValidationError("SKILL.md", `Missing ${SKILL_FILE_NAME}`),
+    );
     return { valid: false, errors };
   }
 
@@ -175,7 +184,12 @@ function validateBundleContents(
   try {
     assertMaxBytes(skillFilePath, SKILL_MARKDOWN_MAX_BYTES);
   } catch (error) {
-    errors.push(new SkillValidationError("SKILL.md", error instanceof Error ? error.message : String(error)));
+    errors.push(
+      new SkillValidationError(
+        "SKILL.md",
+        error instanceof Error ? error.message : String(error),
+      ),
+    );
   }
 
   const rootDir = dirname(skillFilePath);
@@ -183,7 +197,12 @@ function validateBundleContents(
   try {
     realRootDir = realpathSync(rootDir);
   } catch (error) {
-    errors.push(new SkillValidationError("SKILL.md", error instanceof Error ? error.message : String(error)));
+    errors.push(
+      new SkillValidationError(
+        "SKILL.md",
+        error instanceof Error ? error.message : String(error),
+      ),
+    );
     return;
   }
 
@@ -191,19 +210,34 @@ function validateBundleContents(
     const resourcePath = resolve(rootDir, resource);
     try {
       if (!existsSync(resourcePath)) {
-        errors.push(new SkillValidationError("resources", `Missing skill resource: ${resource}`));
+        errors.push(
+          new SkillValidationError(
+            "resources",
+            `Missing skill resource: ${resource}`,
+          ),
+        );
         continue;
       }
 
       const realResourcePath = realpathSync(resourcePath);
       if (!isWithinRoot(realRootDir, realResourcePath)) {
-        errors.push(new SkillValidationError("resources", `Skill resource escapes bundle root: ${resource}`));
+        errors.push(
+          new SkillValidationError(
+            "resources",
+            `Skill resource escapes bundle root: ${resource}`,
+          ),
+        );
         continue;
       }
 
       assertMaxBytes(resourcePath, RESOURCE_MAX_BYTES);
     } catch (error) {
-      errors.push(new SkillValidationError("resources", error instanceof Error ? error.message : String(error)));
+      errors.push(
+        new SkillValidationError(
+          "resources",
+          error instanceof Error ? error.message : String(error),
+        ),
+      );
     }
   }
 }
@@ -250,7 +284,9 @@ function parseSkillBundle(rootDir: string): SkillBundle {
   };
 }
 
-function validateManifestData(data: Record<string, unknown>): SkillValidationError[] {
+function validateManifestData(
+  data: Record<string, unknown>,
+): SkillValidationError[] {
   const errors: SkillValidationError[] = [];
   const requiredFields = [
     "id",
@@ -262,12 +298,25 @@ function validateManifestData(data: Record<string, unknown>): SkillValidationErr
 
   for (const field of requiredFields) {
     if (typeof data[field] !== "string" || data[field].trim() === "") {
-      errors.push(new SkillValidationError(field, `Missing required skill field: ${field}`));
+      errors.push(
+        new SkillValidationError(
+          field,
+          `Missing required skill field: ${field}`,
+        ),
+      );
     }
   }
 
-  if (typeof data.version === "string" && !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(data.version)) {
-    errors.push(new SkillValidationError("version", `Invalid skill version: ${data.version}`));
+  if (
+    typeof data.version === "string" &&
+    !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(data.version)
+  ) {
+    errors.push(
+      new SkillValidationError(
+        "version",
+        `Invalid skill version: ${data.version}`,
+      ),
+    );
   }
 
   if (data.tags !== undefined && !isStringArray(data.tags)) {
@@ -276,13 +325,21 @@ function validateManifestData(data: Record<string, unknown>): SkillValidationErr
 
   if (data.resources !== undefined) {
     if (!isStringArray(data.resources)) {
-      errors.push(new SkillValidationError("resources", "Skill resources must be strings"));
+      errors.push(
+        new SkillValidationError(
+          "resources",
+          "Skill resources must be strings",
+        ),
+      );
     } else {
       for (const resource of data.resources) {
         const normalized = normalizeResourcePath(resource);
         if (!normalized || isPathOutOfBounds(resource)) {
           errors.push(
-            new SkillValidationError("resources", `Invalid skill resource: ${resource}`),
+            new SkillValidationError(
+              "resources",
+              `Invalid skill resource: ${resource}`,
+            ),
           );
         }
       }
@@ -306,14 +363,18 @@ function coerceManifest(data: Record<string, unknown>): SkillManifest {
   }
 
   if (isStringArray(data.resources)) {
-    manifest.resources = data.resources.map((resource) => normalizeResourcePath(resource));
+    manifest.resources = data.resources.map((resource) =>
+      normalizeResourcePath(resource),
+    );
   }
 
   return manifest;
 }
 
 function isStringArray(value: unknown): value is string[] {
-  return Array.isArray(value) && value.every((item) => typeof item === "string");
+  return (
+    Array.isArray(value) && value.every((item) => typeof item === "string")
+  );
 }
 
 function normalizeResourcePath(pathLike: string): string {
@@ -330,7 +391,10 @@ function isPathOutOfBounds(pathLike: string): boolean {
   );
 }
 
-function isDeclaredResource(manifest: SkillManifest, resourcePath: string): boolean {
+function isDeclaredResource(
+  manifest: SkillManifest,
+  resourcePath: string,
+): boolean {
   return (manifest.resources ?? []).some(
     (declared) => normalizeResourcePath(declared) === resourcePath,
   );
@@ -338,7 +402,10 @@ function isDeclaredResource(manifest: SkillManifest, resourcePath: string): bool
 
 function isWithinRoot(rootDir: string, candidatePath: string): boolean {
   const relativePath = relative(rootDir, candidatePath);
-  return relativePath === "" || (!relativePath.startsWith("..") && !isAbsolute(relativePath));
+  return (
+    relativePath === "" ||
+    (!relativePath.startsWith("..") && !isAbsolute(relativePath))
+  );
 }
 
 function assertMaxBytes(pathLike: string, maxBytes: number): void {
@@ -354,6 +421,7 @@ function resolveSkillFilePath(pathLike: string): string {
     return join(resolved, SKILL_FILE_NAME);
   }
 
-  return resolved.endsWith(SKILL_FILE_NAME) ? resolved : join(resolved, SKILL_FILE_NAME);
+  return resolved.endsWith(SKILL_FILE_NAME)
+    ? resolved
+    : join(resolved, SKILL_FILE_NAME);
 }
-

package/src/schemas/entity.schema.json

@@ -62,7 +62,14 @@
     },
     "fact_kind": {
       "type": "string",
-      "enum": ["subject", "property_value", "observation", "meta"]
+      "enum": [
+        "subject",
+        "property_value",
+        "observation",
+        "meta",
+        "predicate_schema",
+        "predicate"
+      ]
     },
     "subject_key": { "type": "string" },
     "property_key": { "type": "string" },
@@ -80,11 +87,26 @@
     "value_bool": { "type": "boolean" },
     "unit": { "type": "string" },
     "scope": { "type": "string" },
-    "polarity": { "type": "string", "enum": ["require", "forbid"] },
+    "polarity": {
+      "type": "string",
+      "enum": ["require", "forbid", "assert", "deny"]
+    },
     "closed_world": { "type": "boolean" },
     "valid_from": { "type": "string" },
     "valid_to": { "type": "string" },
-    "canonical_key": { "type": "string" }
+    "canonical_key": { "type": "string" },
+    "predicate_name": { "type": "string" },
+    "predicate_namespace": { "type": "string" },
+    "predicate_arity": { "type": "integer", "minimum": 1 },
+    "argument_names": { "type": "array", "items": { "type": "string" } },
+    "argument_types": { "type": "array", "items": { "type": "string" } },
+    "argument_descriptions": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "aliases": { "type": "array", "items": { "type": "string" } },
+    "examples": { "type": "array", "items": { "type": "string" } },
+    "predicate_args": { "type": "array", "items": { "type": "string" } }
   },
   "required": [
     "id",
@@ -133,10 +155,65 @@
             { "required": ["closed_world"] },
             { "required": ["valid_from"] },
             { "required": ["valid_to"] },
-            { "required": ["canonical_key"] }
+            { "required": ["canonical_key"] },
+            { "required": ["predicate_name"] },
+            { "required": ["predicate_namespace"] },
+            { "required": ["predicate_arity"] },
+            { "required": ["argument_names"] },
+            { "required": ["argument_types"] },
+            { "required": ["argument_descriptions"] },
+            { "required": ["aliases"] },
+            { "required": ["examples"] },
+            { "required": ["predicate_args"] }
           ]
         }
       }
+    },
+    {
+      "if": {
+        "properties": {
+          "type": { "const": "fact" },
+          "fact_kind": { "const": "predicate_schema" }
+        },
+        "required": ["type", "fact_kind"]
+      },
+      "then": {
+        "required": [
+          "predicate_name",
+          "predicate_arity",
+          "argument_names",
+          "argument_types"
+        ]
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "type": { "const": "fact" },
+          "fact_kind": { "const": "predicate" }
+        },
+        "required": ["type", "fact_kind"]
+      },
+      "then": {
+        "required": ["predicate_name", "predicate_args", "canonical_key"],
+        "properties": {
+          "polarity": { "enum": ["assert", "deny"] }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "type": { "const": "fact" },
+          "fact_kind": { "const": "property_value" }
+        },
+        "required": ["type", "fact_kind"]
+      },
+      "then": {
+        "properties": {
+          "polarity": { "enum": ["require", "forbid"] }
+        }
+      }
     }
   ],
   "additionalProperties": false

package/src/schemas/relationship.schema.json

@@ -16,6 +16,7 @@
         "constrained_by",
         "constrains",
         "requires_property",
+        "requires_predicate",
         "guards",
         "publishes",
         "consumes",

package/dist/public/brief-config.d.ts

@@ -1,4 +0,0 @@
-import { type BriefsConfig } from "../utils/config.js";
-export type { BriefsConfig } from "../utils/config.js";
-export declare function loadBriefConfig(cwd?: string): BriefsConfig;
-//# sourceMappingURL=brief-config.d.ts.map

package/dist/public/brief-config.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"brief-config.d.ts","sourceRoot":"","sources":["../../src/public/brief-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEnE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAsB,GAAG,YAAY,CAoBzE"}

package/dist/public/brief-config.js

@@ -1,21 +0,0 @@
-import { loadConfig } from "../utils/config.js";
-export function loadBriefConfig(cwd = process.cwd()) {
-    const briefs = loadConfig(cwd).briefs;
-    return {
-        enabled: briefs?.enabled ?? true,
-        retention: {
-            maxPerBranch: briefs?.retention?.maxPerBranch ?? 200,
-            maxAgeDays: briefs?.retention?.maxAgeDays ?? 14,
-            keepUnread: briefs?.retention?.keepUnread ?? true,
-        },
-        channels: {
-            vscode: briefs?.channels?.vscode ?? true,
-            tui: briefs?.channels?.tui ?? true,
-        },
-        tui: {
-            toast: briefs?.tui?.toast ?? true,
-            appendPrompt: briefs?.tui?.appendPrompt ?? true,
-            idleDelayMs: briefs?.tui?.idleDelayMs ?? 1500,
-        },
-    };
-}

package/src/public/brief-config.ts

@@ -1,25 +0,0 @@
-import { loadConfig, type BriefsConfig } from "../utils/config.js";
-
-export type { BriefsConfig } from "../utils/config.js";
-
-export function loadBriefConfig(cwd: string = process.cwd()): BriefsConfig { // implements REQ-003
-  const briefs = loadConfig(cwd).briefs;
-
-  return {
-    enabled: briefs?.enabled ?? true,
-    retention: {
-      maxPerBranch: briefs?.retention?.maxPerBranch ?? 200,
-      maxAgeDays: briefs?.retention?.maxAgeDays ?? 14,
-      keepUnread: briefs?.retention?.keepUnread ?? true,
-    },
-    channels: {
-      vscode: briefs?.channels?.vscode ?? true,
-      tui: briefs?.channels?.tui ?? true,
-    },
-    tui: {
-      toast: briefs?.tui?.toast ?? true,
-      appendPrompt: briefs?.tui?.appendPrompt ?? true,
-      idleDelayMs: briefs?.tui?.idleDelayMs ?? 1500,
-    },
-  };
-}