kibi-cli 0.10.1 → 0.11.1

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"}

package/dist/public/skills.js

@@ -0,0 +1,262 @@
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync, } from "node:fs";
+import { dirname, isAbsolute, join, normalize, relative, resolve, } from "node:path";
+import { fileURLToPath } from "node:url";
+import matter from "gray-matter";
+const SKILL_MARKDOWN_MAX_BYTES = 256 * 1024;
+const RESOURCE_MAX_BYTES = 128 * 1024;
+const SKILL_FILE_NAME = "SKILL.md";
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+let bundledSkillsDir = resolve(moduleDir, "skills");
+const defaultBundledSkillsDir = bundledSkillsDir;
+export function setBundledSkillsDir(dir) {
+    bundledSkillsDir = dir;
+}
+export function resetBundledSkillsDir() {
+    bundledSkillsDir = defaultBundledSkillsDir;
+}
+export class SkillNotFoundError extends Error {
+    constructor(id) {
+        super(`Skill not found: ${id}`);
+        this.name = "SkillNotFoundError";
+    }
+}
+export class SkillResourceNotFoundError extends Error {
+    constructor(id, resourcePath) {
+        super(`Skill resource not found: ${id}/${resourcePath}`);
+        this.name = "SkillResourceNotFoundError";
+    }
+}
+export class SkillResourceOutOfBoundsError extends Error {
+    constructor(id, resourcePath) {
+        super(`Skill resource escapes bundle root: ${id}/${resourcePath}`);
+        this.name = "SkillResourceOutOfBoundsError";
+    }
+}
+export class SkillValidationError extends Error {
+    field;
+    constructor(field, message) {
+        super(message);
+        this.name = "SkillValidationError";
+        this.field = field;
+    }
+}
+export class SkillOversizeError extends Error {
+    maxBytes;
+    actualBytes;
+    constructor(pathLike, maxBytes, actualBytes) {
+        super(`Skill file exceeds ${maxBytes} bytes: ${pathLike} (${actualBytes} bytes)`);
+        this.name = "SkillOversizeError";
+        this.maxBytes = maxBytes;
+        this.actualBytes = actualBytes;
+    }
+}
+export function listBundledSkills() {
+    if (!existsSync(bundledSkillsDir)) {
+        return [];
+    }
+    return readdirSync(bundledSkillsDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => join(bundledSkillsDir, entry.name))
+        .filter((rootDir) => existsSync(join(rootDir, SKILL_FILE_NAME)))
+        .map((rootDir) => parseSkillBundle(rootDir).manifest)
+        .sort((left, right) => left.id.localeCompare(right.id));
+}
+export function loadBundledSkill(id) {
+    const rootDir = findBundledSkillRoot(id);
+    if (!rootDir) {
+        throw new SkillNotFoundError(id);
+    }
+    return parseSkillBundle(rootDir);
+}
+export function readBundledSkillResource(id, resourcePath) {
+    const bundle = loadBundledSkill(id);
+    const declaredResource = normalizeResourcePath(resourcePath);
+    if (!declaredResource || isPathOutOfBounds(resourcePath)) {
+        throw new SkillResourceOutOfBoundsError(id, resourcePath);
+    }
+    if (!isDeclaredResource(bundle.manifest, declaredResource)) {
+        throw new SkillResourceNotFoundError(id, resourcePath);
+    }
+    const candidatePath = resolve(bundle.rootDir, declaredResource);
+    let realResourcePath;
+    let realRootDir;
+    try {
+        realResourcePath = realpathSync(candidatePath);
+        realRootDir = realpathSync(bundle.rootDir);
+    }
+    catch {
+        throw new SkillResourceNotFoundError(id, resourcePath);
+    }
+    if (!isWithinRoot(realRootDir, realResourcePath)) {
+        throw new SkillResourceOutOfBoundsError(id, resourcePath);
+    }
+    assertMaxBytes(candidatePath, RESOURCE_MAX_BYTES);
+    return readFileSync(candidatePath, "utf8");
+}
+export function validateSkillBundle(pathLike) {
+    const skillFilePath = resolveSkillFilePath(pathLike);
+    const errors = [];
+    if (!existsSync(skillFilePath)) {
+        errors.push(new SkillValidationError("SKILL.md", `Missing ${SKILL_FILE_NAME}`));
+        return { valid: false, errors };
+    }
+    const parsed = matter(readFileSync(skillFilePath, "utf8"));
+    errors.push(...validateManifestData(parsed.data));
+    if (errors.length === 0) {
+        validateBundleContents(skillFilePath, coerceManifest(parsed.data), errors);
+    }
+    return { valid: errors.length === 0, errors };
+}
+function validateBundleContents(skillFilePath, manifest, errors) {
+    try {
+        assertMaxBytes(skillFilePath, SKILL_MARKDOWN_MAX_BYTES);
+    }
+    catch (error) {
+        errors.push(new SkillValidationError("SKILL.md", error instanceof Error ? error.message : String(error)));
+    }
+    const rootDir = dirname(skillFilePath);
+    let realRootDir;
+    try {
+        realRootDir = realpathSync(rootDir);
+    }
+    catch (error) {
+        errors.push(new SkillValidationError("SKILL.md", error instanceof Error ? error.message : String(error)));
+        return;
+    }
+    for (const resource of manifest.resources ?? []) {
+        const resourcePath = resolve(rootDir, resource);
+        try {
+            if (!existsSync(resourcePath)) {
+                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}`));
+                continue;
+            }
+            assertMaxBytes(resourcePath, RESOURCE_MAX_BYTES);
+        }
+        catch (error) {
+            errors.push(new SkillValidationError("resources", error instanceof Error ? error.message : String(error)));
+        }
+    }
+}
+function findBundledSkillRoot(id) {
+    if (!existsSync(bundledSkillsDir)) {
+        return undefined;
+    }
+    for (const entry of readdirSync(bundledSkillsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const rootDir = join(bundledSkillsDir, entry.name);
+        const skillFilePath = join(rootDir, SKILL_FILE_NAME);
+        if (!existsSync(skillFilePath)) {
+            continue;
+        }
+        const manifest = parseSkillBundle(rootDir).manifest;
+        if (manifest.id === id) {
+            return rootDir;
+        }
+    }
+    return undefined;
+}
+function parseSkillBundle(rootDir) {
+    const skillFilePath = join(rootDir, SKILL_FILE_NAME);
+    assertMaxBytes(skillFilePath, SKILL_MARKDOWN_MAX_BYTES);
+    const parsed = matter(readFileSync(skillFilePath, "utf8"));
+    const errors = validateManifestData(parsed.data);
+    if (errors.length > 0) {
+        throw errors[0];
+    }
+    return {
+        manifest: coerceManifest(parsed.data),
+        body: parsed.content,
+        rootDir: resolve(rootDir),
+    };
+}
+function validateManifestData(data) {
+    const errors = [];
+    const requiredFields = [
+        "id",
+        "name",
+        "description",
+        "version",
+        "kibiCompatibility",
+    ];
+    for (const field of requiredFields) {
+        if (typeof data[field] !== "string" || data[field].trim() === "") {
+            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 (data.tags !== undefined && !isStringArray(data.tags)) {
+        errors.push(new SkillValidationError("tags", "Skill tags must be strings"));
+    }
+    if (data.resources !== undefined) {
+        if (!isStringArray(data.resources)) {
+            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}`));
+                }
+            }
+        }
+    }
+    return errors;
+}
+function coerceManifest(data) {
+    const manifest = {
+        id: String(data.id),
+        name: String(data.name),
+        description: String(data.description),
+        version: String(data.version),
+        kibiCompatibility: String(data.kibiCompatibility),
+    };
+    if (isStringArray(data.tags)) {
+        manifest.tags = data.tags;
+    }
+    if (isStringArray(data.resources)) {
+        manifest.resources = data.resources.map((resource) => normalizeResourcePath(resource));
+    }
+    return manifest;
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function normalizeResourcePath(pathLike) {
+    return normalize(pathLike).replaceAll("\\", "/");
+}
+function isPathOutOfBounds(pathLike) {
+    const normalized = normalizeResourcePath(pathLike);
+    return (isAbsolute(pathLike) ||
+        normalized === ".." ||
+        normalized.startsWith("../") ||
+        normalized.includes("/../"));
+}
+function isDeclaredResource(manifest, resourcePath) {
+    return (manifest.resources ?? []).some((declared) => normalizeResourcePath(declared) === resourcePath);
+}
+function isWithinRoot(rootDir, candidatePath) {
+    const relativePath = relative(rootDir, candidatePath);
+    return relativePath === "" || (!relativePath.startsWith("..") && !isAbsolute(relativePath));
+}
+function assertMaxBytes(pathLike, maxBytes) {
+    const size = statSync(pathLike).size;
+    if (size > maxBytes) {
+        throw new SkillOversizeError(pathLike, maxBytes, size);
+    }
+}
+function resolveSkillFilePath(pathLike) {
+    const resolved = resolve(pathLike);
+    if (existsSync(resolved) && statSync(resolved).isDirectory()) {
+        return join(resolved, SKILL_FILE_NAME);
+    }
+    return resolved.endsWith(SKILL_FILE_NAME) ? resolved : join(resolved, SKILL_FILE_NAME);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cli",
-  "version": "0.10.1",
+  "version": "0.11.1",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {
@@ -19,7 +19,7 @@
     "src/public"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json && mkdir -p dist/public/skills && cp -r src/public/skills/. dist/public/skills/",
     "prepack": "npm run build"
   },
   "exports": {
@@ -87,6 +87,10 @@
       "types": "./dist/public/operational-artifacts.d.ts",
       "default": "./dist/public/operational-artifacts.js"
     },
+    "./skills": {
+      "types": "./dist/public/skills.d.ts",
+      "default": "./dist/public/skills.js"
+    },
     "./ignore-policy": {
       "types": "./dist/public/ignore-policy.d.ts",
       "import": "./dist/public/ignore-policy.js",

package/src/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/src/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
+```