kibi-cli 0.11.1 → 0.11.3

package/src/public/skills/kibi-usage/SKILL.md

@@ -48,6 +48,24 @@ Relationship direction is fixed and semantic. Getting it wrong breaks traceabili
 
 See `resources/relationship-directions.md` for detailed payload examples.
 
+## Symbol-First Traceability
+
+Trace code through `symbol` entities, not inline legacy comments. Do not use legacy `// implements REQ-xxx` comments as the primary marker for new or modified code. If a symbol is new or its requirement ownership changes, create or update the `symbol` entity and add an `implements` relationship from the symbol to the requirement.
+
+Use comments only as a temporary backward-compatibility fallback when the symbol manifest cannot be updated in the same task. Prefer durable symbol coordinates in `documentation/symbols.yaml` and `documentation/symbol-coordinates.yaml`, then link those symbols through MCP relationships.
+
+```yaml
+# Preferred traceability model
+symbol:
+  id: SYM-admin-billing-policy
+  title: Admin billing policy check
+  status: active
+relationships:
+  - type: implements
+    from: SYM-admin-billing-policy
+    to: REQ-ADMIN-BILLING-POLICY
+```
+
 ## Strict Fact Lane
 
 Normative requirements that must participate in contradiction blocking use the strict fact lane. Create a `fact_kind: subject` fact and link it from the requirement via `constrains`. Create a `fact_kind: property_value` fact and link it via `requires_property`.
@@ -75,6 +93,67 @@ relationships:
 
 See `resources/fact-lanes.md` for the full strict vs observation lane comparison.
 
+### Granular fact examples for coherence checks
+
+Model one semantic claim per strict `property_value` fact. Reusing the same `subject_key` and `property_key` lets `domain-contradictions` compare requirements mechanically.
+
+Incoherent role-set example: `REQ-ROLE-SET-2` says the allowed user roles are exactly `[user, admin]`, while `REQ-ROLE-SET-3` says the same property is exactly `[user, admin, superadmin]`. Both constrain `FACT-USER-ROLES` and require different values for `user.roles.allowed_set`, so they cannot both be current.
+
+```yaml
+subject:
+  id: FACT-USER-ROLES
+  fact_kind: subject
+  subject_key: user.roles
+
+property_values:
+  - id: FACT-USER-ROLES-ALLOWED-2
+    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
+    fact_kind: property_value
+    subject_key: user.roles
+    property_key: user.roles.allowed_set
+    operator: eq
+    value_type: list
+    value_json: '["user", "admin", "superadmin"]'
+
+requirements:
+  - id: REQ-ROLE-SET-2
+    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 }
+  - id: REQ-ROLE-SET-3
+    relationships:
+      - { 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 }
+```
+
+Incoherent permission example: `REQ-ADMIN-CAN-MANAGE-BILLING` says `admin` can manage billing, while `REQ-ONLY-SUPERADMIN-MANAGES-BILLING` says the only allowed actor is `superadmin`. Model both against `billing.manage.allowed_actor` with `operator: eq` so the conflict is explicit.
+
+```yaml
+property_values:
+  - id: FACT-BILLING-MANAGE-ACTOR-ADMIN
+    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
+    fact_kind: property_value
+    subject_key: billing.manage
+    property_key: billing.manage.allowed_actor
+    operator: eq
+    value_type: string
+    value_string: superadmin
+```
+
+If a new requirement intentionally changes a value, create a replacement requirement and link the old requirement to the new one with `supersedes` instead of leaving two current contradictory requirements.
+
 ## Fact vs Flag
 
 Use `flag` for runtime or config gates only. Feature flags, kill-switches, and deferred capabilities are valid `flag` entities.
@@ -110,6 +189,7 @@ Call `kb_status` when you suspect the branch KB is stale or when switching conte
 | Anti-Pattern | Problem | Remediation |
 |-------------|---------|-------------|
 | Reversed relationship direction | Traceability queries break | Verify direction against the relationship table above |
+| Legacy implements comments | Comments are not durable queryable symbols | Create or update a `symbol` entity and link it to the requirement |
 | Bug-as-flag | `flag` misused for defect tracking | Use `fact` with `fact_kind: observation` or `meta` |
 | Parallel upserts | Lock contention and nondeterminism | Execute `kb_upsert` calls sequentially |
 | Embedded scenarios in reqs | Violates canonical traceability chain | Create separate `req`, `scen`, and `test` entities |

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/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,
-    },
-  };
-}