kibi-cli 0.11.0 → 0.11.3

package/schema/config.json

@@ -61,74 +61,6 @@
       "description": "[DEPRECATED] No longer used. Branch lifecycle now follows git naturally without requiring a configured default. This field is ignored but kept for backward compatibility.",
       "deprecated": true
     },
-    "briefs": {
-      "type": "object",
-      "description": "Configuration for shared brief delivery defaults",
-      "properties": {
-        "enabled": {
-          "type": "boolean",
-          "default": true
-        },
-        "retention": {
-          "type": "object",
-          "properties": {
-            "maxPerBranch": {
-              "type": "integer",
-              "minimum": 1,
-              "maximum": 10000,
-              "default": 200
-            },
-            "maxAgeDays": {
-              "type": "integer",
-              "minimum": 1,
-              "maximum": 3650,
-              "default": 14
-            },
-            "keepUnread": {
-              "type": "boolean",
-              "default": true
-            }
-          },
-          "additionalProperties": false
-        },
-        "channels": {
-          "type": "object",
-          "properties": {
-            "vscode": {
-              "type": "boolean",
-              "default": true
-            },
-            "tui": {
-              "type": "boolean",
-              "default": true
-            }
-          },
-          "additionalProperties": false
-        },
-        "tui": {
-          "type": "object",
-          "properties": {
-            "toast": {
-              "type": "boolean",
-              "default": true
-            },
-            "appendPrompt": {
-              "type": "boolean",
-              "default": true
-            },
-            "idleDelayMs": {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 60000,
-              "default": 1500,
-              "description": "Delay in milliseconds after session.idle before idle-brief generation is attempted"
-            }
-          },
-          "additionalProperties": false
-        }
-      },
-      "additionalProperties": false
-    },
     "checks": {
       "type": "object",
       "description": "Configuration for KB validation rules",

package/src/public/ignore-policy.ts

@@ -1,4 +1,10 @@
-import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import {
+  type Dirent,
+  existsSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+} from "node:fs";
 import * as path from "node:path";
 import ignore from "ignore";
 
@@ -51,7 +57,7 @@ export function createRepoIgnorePolicy(workspaceRoot: string): IgnorePolicy {
   const nestedPatterns = new Map<string, string[]>();
 
   function walk(dirAbs: string) {
-    let entries;
+    let entries: Dirent[];
     try {
       entries = readdirSync(dirAbs, { withFileTypes: true });
     } catch {
@@ -95,7 +101,9 @@ export function createRepoIgnorePolicy(workspaceRoot: string): IgnorePolicy {
   }
 
   // Prepare nested directories sorted by specificity (longest first)
-  const nestedDirsSorted = Array.from(nestedIgnoreMap.keys()).sort((a, b) => b.length - a.length);
+  const nestedDirsSorted = Array.from(nestedIgnoreMap.keys()).sort(
+    (a, b) => b.length - a.length,
+  );
 
   function isPathOutsideWorkspace(absPath: string): boolean {
     const rel = path.relative(root, absPath);
@@ -111,9 +119,14 @@ export function createRepoIgnorePolicy(workspaceRoot: string): IgnorePolicy {
     return false;
   }
 
-  function isIgnoredInternal(inputPath: string): { ignored: boolean; reason?: string } {
+  function isIgnoredInternal(inputPath: string): {
+    ignored: boolean;
+    reason?: string;
+  } {
     // Resolve to absolute and relative path inside workspace
-    const abs = path.isAbsolute(inputPath) ? path.resolve(inputPath) : path.resolve(root, inputPath);
+    const abs = path.isAbsolute(inputPath)
+      ? path.resolve(inputPath)
+      : path.resolve(root, inputPath);
 
     if (path.isAbsolute(inputPath) && isPathOutsideWorkspace(abs)) {
       return { ignored: true, reason: "outside_workspace" };
@@ -123,7 +136,8 @@ export function createRepoIgnorePolicy(workspaceRoot: string): IgnorePolicy {
     const relPosix = toPosix(rel);
 
     // Hard denylist always wins
-    if (matchesHardDeny(relPosix)) return { ignored: true, reason: "hard_deny" };
+    if (matchesHardDeny(relPosix))
+      return { ignored: true, reason: "hard_deny" };
 
     // Root .gitignore
     try {
@@ -147,11 +161,13 @@ export function createRepoIgnorePolicy(workspaceRoot: string): IgnorePolicy {
     for (const dirRel of nestedDirsSorted) {
       // dirRel is '.' for nested at root which we skipped, so dirRel will be like 'docs'
       if (dirRel === ".") continue;
-      if (relPosix === dirRel || relPosix.startsWith(dirRel + "/")) {
-        const sub = relPosix === dirRel ? "." : relPosix.slice(dirRel.length + 1);
-        const ig = nestedIgnoreMap.get(dirRel)!;
+      if (relPosix === dirRel || relPosix.startsWith(`${dirRel}/`)) {
+        const sub =
+          relPosix === dirRel ? "." : relPosix.slice(dirRel.length + 1);
+        const ig = nestedIgnoreMap.get(dirRel);
+        if (!ig) continue;
         try {
-          if (ig && ig.ignores(sub)) return { ignored: true, reason: "gitignored" };
+          if (ig.ignores(sub)) return { ignored: true, reason: "gitignored" };
         } catch (e) {
           // noop
         }

package/src/public/operational-artifacts.ts

@@ -1,4 +1,5 @@
-export function isOperationalArtifactPath(pathLike: string): boolean { // implements REQ-001
+export function isOperationalArtifactPath(pathLike: string): boolean {
+  // implements REQ-001
   const normalized = pathLike.replaceAll("\\", "/");
 
   return /(^|\/)\.sisyphus\//.test(normalized);

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

@@ -0,0 +1,205 @@
+---
+id: kibi-usage
+name: Kibi Usage
+description: Guides agents to use Kibi MCP, facts, relationships, and validation correctly
+version: 1.0.0
+kibiCompatibility: ">=0.11.0"
+tags:
+  - kibi
+  - mcp
+  - knowledge-base
+  - traceability
+  - agent-guidance
+resources:
+  - resources/relationship-directions.md
+  - resources/fact-lanes.md
+  - resources/workflows.md
+---
+
+# Kibi Usage
+
+Consult this skill before any Kibi knowledge base operation, on first interaction with a Kibi-enabled repo, after detecting stale or dirty KB status, and before performing mutations.
+
+## MCP-Only Rules
+
+Interact with the knowledge base exclusively through MCP tools. Do not read or edit files inside `.kb/` directly. Do not run any `kibi` CLI commands from the agent session. The MCP surface is the only sanctioned interface for agents.
+
+## Discovery-First Workflow
+
+Always discover before you mutate. Start with `kb_search` for exploratory discovery across metadata and markdown body text. Split broad queries into 1-3 focused probes. Review top hits for relevance before concluding the KB lacks knowledge.
+
+Follow up with `kb_query` for exact lookups by `id`, `type`, `tags`, or `sourceFile`. Call `kb_status` to inspect branch attachment and freshness when stale context would affect decisions. Only after discovery and confirmation should you mutate.
+
+## Relationship Directions
+
+Relationship direction is fixed and semantic. Getting it wrong breaks traceability queries and validation.
+
+| Relationship | Direction | Meaning |
+|-------------|-----------|---------|
+| `implements` | symbol -> req | Symbol owns or implements requirement behavior |
+| `specified_by` | req -> scenario | Requirement is specified by a scenario |
+| `verified_by` | req/scenario -> test | Requirement or scenario is verified by a test |
+| `validates` | test -> req/scenario | Test validates a requirement or scenario |
+| `executable_for` | symbol -> test | Symbol is executable test code for a test entity |
+| `constrains` | req -> fact(subject) | Requirement constrains a domain fact |
+| `requires_property` | req -> fact(property_value) | Requirement requires a property value |
+| `supersedes` | old-req -> new-req | Old requirement is replaced by new requirement |
+| `covered_by` | symbol -> test | Production symbol has coverage evidence from a test |
+
+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`.
+
+```yaml
+# Fact entity
+id: FACT-USER-ROLE
+title: User Role Assignment
+status: active
+fact_kind: subject
+subject_key: user.role_assignment
+
+# Requirement entity
+id: REQ-019
+title: Users can have up to 3 roles
+status: open
+relationships:
+  - type: constrains
+    from: REQ-019
+    to: FACT-USER-ROLE
+  - type: requires_property
+    from: REQ-019
+    to: FACT-LIMIT-3
+```
+
+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.
+
+Bugs, incidents, and workarounds belong in `fact` entities with `fact_kind: observation` or `meta`. These fact kinds are excluded from contradiction inference, making them appropriate for non-blocking evidence.
+
+Anti-example: do not create a `flag` named `BUG-123` to track a defect. Create a `fact` with `fact_kind: observation` instead.
+
+## Create-Before-Link
+
+Always confirm or create endpoint entities before linking them. Query target IDs with `kb_query` first. If an endpoint does not exist, create it with `kb_upsert` before creating the relationship. Creating relationships to non-existent entities produces dangling references that `kb_check` will flag.
+
+## Sequential Upserts
+
+Never fire `kb_upsert` calls in parallel. Execute them sequentially to avoid lock contention and ensure deterministic ordering. This is especially important when creating chains of related entities.
+
+## Targeted and Final Checks
+
+Run `kb_check` with specific rules during iteration for fast feedback. For example, use `rules: ["required-fields", "no-dangling-refs"]` after small changes. Run a full `kb_check` without rule filters before declaring work complete.
+
+## Domain Contradictions and Evolution
+
+The `domain-contradictions` rule detects conflicts between strict-lane facts linked to requirements. When a contradiction is found, the supported escape hatch is `supersedes`: create a new requirement that supersedes the old one, then link the new requirement to updated facts.
+
+Use `kb_model_requirement` for automated strict-fact modeling. It generates the subject and property_value facts, links them via `constrains` and `requires_property`, and handles low-confidence downgrades to `observation` facts automatically.
+
+## Stale or Dirty KB Handling
+
+Call `kb_status` when you suspect the branch KB is stale or when switching context. Report freshness findings to the user rather than relying on outdated KB context. If `kb_status` indicates a schema migration is needed, ask the user or operator to handle it outside the agent session.
+
+## Anti-Patterns and Remediation
+
+| 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 |
+| Missing `kb_check` | Undetected dangling refs and violations | Run targeted checks during work, full check at completion |
+| Tags as multi-ID lookup | Tags are metadata, not identifiers | Use `kb_query` with explicit `id` values |
+| `relates_to` for strict modeling | Loses contradiction safety | Use `constrains` and `requires_property` instead |
+
+Before/after for reversed direction:
+
+- Wrong: `relationships: [{ type: "implements", from: "REQ-001", to: "SYM-001" }]`
+- Right: `relationships: [{ type: "implements", from: "SYM-001", to: "REQ-001" }]`
+
+See `resources/workflows.md` for the golden-path discovery to validation sequence.

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

@@ -0,0 +1,123 @@
+# Fact Lanes
+
+## Strict Lane (Contradiction-Safe)
+
+### fact_kind: subject
+```yaml
+id: FACT-USER-ROLE
+title: User Role Assignment
+status: active
+fact_kind: subject
+subject_key: user.role_assignment
+```
+
+### fact_kind: property_value
+```yaml
+id: FACT-LIMIT-3
+title: Maximum of Three Roles
+status: active
+fact_kind: property_value
+subject_key: user.role_assignment
+property_key: max_roles
+operator: lte
+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
+For bug records, incident notes, and observed behavior.
+```yaml
+id: FACT-BUG-123
+title: Login fails on Safari 17
+status: active
+fact_kind: observation
+```
+
+### fact_kind: meta
+For governance notes, process commentary, and workaround documentation.
+```yaml
+id: FACT-WORKAROUND-456
+title: Temporary cache bypass for v2 migration
+status: active
+fact_kind: meta
+```

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

@@ -0,0 +1,89 @@
+# Relationship Directions
+
+## Direction Table
+
+| Relationship | Source -> Target | Semantic Meaning |
+|-------------|------------------|------------------|
+| `implements` | symbol -> req | Production code symbol owns or implements requirement behavior |
+| `specified_by` | req -> scenario | Requirement is specified by a BDD scenario |
+| `verified_by` | req/scenario -> test | Requirement or scenario is verified by a test case |
+| `validates` | test -> req/scenario | Test validates a requirement or scenario (inverse of verified_by) |
+| `executable_for` | symbol -> test | Test symbol (code) is executable code for a test entity |
+| `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` | old-req -> new-req | Old requirement is formally replaced by a new requirement |
+| `covered_by` | symbol -> test | Production symbol has test coverage evidence |
+
+## Valid Payload Examples
+
+### implements
+```yaml
+relationships:
+  - type: implements
+    from: SYM-001
+    to: REQ-001
+```
+
+### specified_by
+```yaml
+relationships:
+  - type: specified_by
+    from: REQ-001
+    to: SCEN-001
+```
+
+### verified_by
+```yaml
+relationships:
+  - type: verified_by
+    from: REQ-001
+    to: TEST-001
+```
+
+### validates
+```yaml
+relationships:
+  - type: validates
+    from: TEST-001
+    to: SCEN-001
+```
+
+### executable_for
+```yaml
+relationships:
+  - type: executable_for
+    from: SYM-test-login
+    to: TEST-001
+```
+
+### constrains
+```yaml
+relationships:
+  - type: constrains
+    from: REQ-019
+    to: FACT-USER-ROLE
+```
+
+### requires_property
+```yaml
+relationships:
+  - type: requires_property
+    from: REQ-019
+    to: FACT-LIMIT-3
+```
+
+### supersedes
+```yaml
+relationships:
+  - type: supersedes
+    from: REQ-001
+    to: REQ-001-v2
+```
+
+### covered_by
+```yaml
+relationships:
+  - type: covered_by
+    from: SYM-handler
+    to: TEST-005
+```

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

@@ -0,0 +1,28 @@
+# Workflows
+
+## Discovery to Validation Sequence
+
+The canonical workflow for any KB operation follows this pattern:
+
+1. **Discover**: `kb_search` with focused probes
+2. **Confirm**: `kb_query` for exact IDs and state
+3. **Inspect**: `kb_status` when freshness matters
+4. **Create endpoints**: `kb_upsert` for new entities (sequential)
+5. **Link**: `kb_upsert` with relationship rows (sequential)
+6. **Validate**: `kb_check` with targeted rules during work, full check at completion
+
+## Creating a New Feature
+```
+1. kb_search to discover existing requirements and related knowledge
+2. kb_query to confirm exact IDs and source-linked context
+3. kb_upsert for new or updated requirements (include relationship rows)
+4. kb_check with targeted rules
+```
+
+## Fixing a Traceability Gap
+```
+1. kb_query --sourceFile <code-file> to find linked entities
+2. kb_find_gaps --type req --missing-rel specified_by to find orphan requirements
+3. kb_upsert to add missing relationship rows (sequential)
+4. kb_check with rules: ["no-dangling-refs", "symbol-traceability"]
+```