kibi-cli 0.11.0 → 0.11.3

package/dist/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/dist/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/dist/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/dist/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"]
+```

package/dist/public/skills.d.ts

@@ -0,0 +1,42 @@
+export declare function setBundledSkillsDir(dir: string): void;
+export declare function resetBundledSkillsDir(): void;
+export interface SkillManifest {
+    id: string;
+    name: string;
+    description: string;
+    version: string;
+    kibiCompatibility: string;
+    tags?: string[];
+    resources?: string[];
+}
+export interface SkillBundle {
+    manifest: SkillManifest;
+    body: string;
+    rootDir: string;
+}
+export declare class SkillNotFoundError extends Error {
+    constructor(id: string);
+}
+export declare class SkillResourceNotFoundError extends Error {
+    constructor(id: string, resourcePath: string);
+}
+export declare class SkillResourceOutOfBoundsError extends Error {
+    constructor(id: string, resourcePath: string);
+}
+export declare class SkillValidationError extends Error {
+    readonly field: string;
+    constructor(field: string, message: string);
+}
+export declare class SkillOversizeError extends Error {
+    readonly maxBytes: number;
+    readonly actualBytes: number;
+    constructor(pathLike: string, maxBytes: number, actualBytes: number);
+}
+export declare function listBundledSkills(): SkillManifest[];
+export declare function loadBundledSkill(id: string): SkillBundle;
+export declare function readBundledSkillResource(id: string, resourcePath: string): string;
+export declare function validateSkillBundle(pathLike: string): {
+    valid: boolean;
+    errors: SkillValidationError[];
+};
+//# sourceMappingURL=skills.d.ts.map

package/dist/public/skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/public/skills.ts"],"names":[],"mappings":"AA0BA,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAErD;AAED,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,aAAa,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,EAAE,EAAE,MAAM;CAIvB;AAED,qBAAa,0BAA2B,SAAQ,KAAK;gBACvC,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM;CAI7C;AAED,qBAAa,6BAA8B,SAAQ,KAAK;gBAC1C,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM;CAI7C;AAED,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK3C;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAEjB,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM;CAQpE;AAED,wBAAgB,iBAAiB,IAAI,aAAa,EAAE,CAYnD;AAED,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,CAQxD;AAED,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,MAAM,EACV,YAAY,EAAE,MAAM,GACnB,MAAM,CA6BR;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG;IACrD,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,oBAAoB,EAAE,CAAC;CAChC,CAoBA"}