kibi-cli 0.11.0 → 0.11.1

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAwCA,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AA8CA,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/dist/cli.js

@@ -28,6 +28,7 @@ import { initCommand } from "./commands/init.js";
 import { migrateCommand } from "./commands/migrate.js";
 import { queryCommand } from "./commands/query.js";
 import { searchCommand } from "./commands/search.js";
+import { skillsListCommand, skillsLoadCommand, skillsReadCommand, skillsValidateCommand, } from "./commands/skills.js";
 import { statusCommand } from "./commands/status.js";
 import { syncCommand } from "./commands/sync.js";
 import { usageMetricsCommand } from "./commands/usage-metrics.js";
@@ -176,6 +177,41 @@ program
     .action(withExitCode(async (options) => {
     return usageMetricsCommand(options);
 }));
+const skillsProgram = program
+    .command("skills")
+    .description("Manage bundled markdown skills");
+skillsProgram
+    .command("list")
+    .description("List bundled markdown skills")
+    .option("--format <format>", "Output format: json|table", "table")
+    .action(withExitCode(async (options) => {
+    return skillsListCommand(options);
+}));
+skillsProgram
+    .command("load")
+    .description("Load a bundled markdown skill")
+    .argument("<id>", "Bundled skill ID")
+    .option("--format <format>", "Output format: json|markdown", "markdown")
+    .action(withExitCode(async (id, options) => {
+    return skillsLoadCommand(id, options);
+}));
+skillsProgram
+    .command("read")
+    .description("Read a declared bundled skill resource")
+    .argument("<id>", "Bundled skill ID")
+    .argument("<resource>", "Declared resource path")
+    .option("--format <format>", "Output format: text|json", "text")
+    .action(withExitCode(async (id, resource, options) => {
+    return skillsReadCommand(id, resource, options);
+}));
+skillsProgram
+    .command("validate")
+    .description("Validate a bundled markdown skill path")
+    .argument("<path>", "Skill bundle directory or SKILL.md path")
+    .option("--format <format>", "Output format: json|table", "table")
+    .action(withExitCode(async (pathLike, options) => {
+    return skillsValidateCommand(pathLike, options);
+}));
 program
     .command("branch")
     .description("Manage branch KBs")

package/dist/commands/skills.d.ts

@@ -0,0 +1,14 @@
+import type { CommandResult } from "../cli.js";
+interface FormatOptions<TFormat extends string> {
+    format?: TFormat;
+}
+type ListFormat = "json" | "table";
+type LoadFormat = "json" | "markdown";
+type ReadFormat = "text" | "json";
+type ValidateFormat = "json" | "table";
+export declare function skillsListCommand(options: FormatOptions<ListFormat>): Promise<CommandResult | undefined>;
+export declare function skillsLoadCommand(id: string, options: FormatOptions<LoadFormat>): Promise<CommandResult | undefined>;
+export declare function skillsReadCommand(id: string, resource: string, options: FormatOptions<ReadFormat>): Promise<CommandResult | undefined>;
+export declare function skillsValidateCommand(pathLike: string, options: FormatOptions<ValidateFormat>): Promise<CommandResult | undefined>;
+export {};
+//# sourceMappingURL=skills.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/commands/skills.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAU/C,UAAU,aAAa,CAAC,OAAO,SAAS,MAAM;IAC5C,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,KAAK,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC;AACnC,KAAK,UAAU,GAAG,MAAM,GAAG,UAAU,CAAC;AACtC,KAAK,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAClC,KAAK,cAAc,GAAG,MAAM,GAAG,OAAO,CAAC;AAGvC,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,aAAa,CAAC,UAAU,CAAC,GACjC,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAUpC;AAED,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,aAAa,CAAC,UAAU,CAAC,GACjC,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAgBpC;AAED,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,aAAa,CAAC,UAAU,CAAC,GACjC,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAUpC;AAED,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,aAAa,CAAC,cAAc,CAAC,GACrC,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAepC"}

package/dist/commands/skills.js

@@ -0,0 +1,86 @@
+import { createHash } from "node:crypto";
+import Table from "cli-table3";
+import { listBundledSkills, loadBundledSkill, readBundledSkillResource, validateSkillBundle, } from "kibi-cli/skills";
+// implements REQ-003
+export async function skillsListCommand(options) {
+    return handleSkillCommand(() => {
+        const skills = listBundledSkills();
+        if (options.format === "json") {
+            console.log(JSON.stringify(skills, null, 2));
+            return;
+        }
+        console.log(renderSkillsTable(skills));
+    });
+}
+export async function skillsLoadCommand(id, options) {
+    return handleSkillCommand(() => {
+        const bundle = loadBundledSkill(id);
+        if (options.format === "json") {
+            console.log(JSON.stringify({
+                metadata: bundle.manifest,
+                body: bundle.body,
+                resources: bundle.manifest.resources ?? [],
+                contentHash: createHash("sha256").update(bundle.body).digest("hex"),
+                sourceType: "bundled",
+            }, null, 2));
+            return;
+        }
+        process.stdout.write(bundle.body.endsWith("\n") ? bundle.body : `${bundle.body}\n`);
+    });
+}
+export async function skillsReadCommand(id, resource, options) {
+    return handleSkillCommand(() => {
+        const contents = readBundledSkillResource(id, resource);
+        if (options.format === "json") {
+            console.log(JSON.stringify({ id, resource, contents }, null, 2));
+            return;
+        }
+        process.stdout.write(contents.endsWith("\n") ? contents : `${contents}\n`);
+    });
+}
+export async function skillsValidateCommand(pathLike, options) {
+    return handleSkillCommand(() => {
+        const result = validateSkillBundle(pathLike);
+        const printable = {
+            valid: result.valid,
+            errors: result.errors.map(formatValidationError),
+        };
+        if (options.format === "json") {
+            console.log(JSON.stringify(printable, null, 2));
+            return;
+        }
+        console.log(renderValidationTable(printable));
+    });
+}
+function handleSkillCommand(action) {
+    try {
+        action();
+        return undefined;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(message);
+        return { exitCode: 1 };
+    }
+}
+function renderSkillsTable(skills) {
+    const table = new Table({ head: ["ID", "Name", "Version", "Description"] });
+    for (const skill of skills) {
+        table.push([skill.id, skill.name, skill.version, skill.description]);
+    }
+    return table.toString();
+}
+function formatValidationError(error) {
+    return { field: error.field, message: error.message };
+}
+function renderValidationTable(result) {
+    const table = new Table({ head: ["Valid", "Field", "Message"] });
+    if (result.errors.length === 0) {
+        table.push([String(result.valid), "", ""]);
+        return table.toString();
+    }
+    for (const error of result.errors) {
+        table.push([String(result.valid), error.field, error.message]);
+    }
+    return table.toString();
+}

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

@@ -0,0 +1,125 @@
+---
+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.
+
+## 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.
+
+## 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 |
+| 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,45 @@
+# 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
+```
+
+## 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,35 @@
+# 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"]
+```
+
+## 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/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;CAMpE;AAED,wBAAgB,iBAAiB,IAAI,aAAa,EAAE,CAWnD;AAED,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,CAOxD;AAED,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,MAAM,EACV,YAAY,EAAE,MAAM,GACnB,MAAM,CA4BR;AAED,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,GACf;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,oBAAoB,EAAE,CAAA;CAAE,CAiBpD"}