kibi-cli 0.14.0 → 0.17.0

package/dist/public/skills/kibi-usage/resources/ui-requirements.md

@@ -0,0 +1,96 @@
+# UI / Visual Requirement Modeling
+
+Optional, per-project lane for recording what the screen should look like so UI edits cannot
+silently drift from the spec. Non-UI projects skip it entirely; no check rule requires it.
+
+## Three layers
+
+1. **Prose `req`** — the full on-screen description lives in the requirement body as the
+   searchable anchor agents discover with `kb_search` / `kb_query`.
+2. **Strict facts** — checkable visual invariants as `fact_kind: subject` (`subject_key`,
+   linked `constrains`) plus `fact_kind: property_value` (`property_key`, `operator`, typed
+   `value_*`, linked `requires_property`). Incompatible values on the same subject/property
+   from two current requirements are rejected on write unless `supersedes`.
+3. **Relational predicates** — ground `fact_kind: predicate` linked with `requires_predicate`.
+   The built-in `visual_layout_rule(subject, relation, target)` covers "X must remain visually
+   aligned with Y" (relation `aligned_with`). Other relational layout claims need a
+   project-local `predicate_schema` when the task authorizes ontology extension.
+
+Kibi enforces stated facts and links, not pixels. Freeform spatial prose is stored and
+searchable but is not machine-checked.
+
+## Button position
+
+```yaml
+id: FACT-UI-SUBMIT-REGION
+fact_kind: subject
+subject_key: settings.screen.submit_button
+```
+
+```yaml
+id: FACT-UI-SUBMIT-POSITION
+fact_kind: property_value
+subject_key: settings.screen.submit_button
+property_key: position
+operator: eq
+value_type: string
+value_string: bottom_right
+canonical_key: settings.screen.submit_button.position.eq.bottom_right
+```
+
+Link both facts from the requirement:
+
+```yaml
+id: REQ-UI-SETTINGS
+relationships:
+  - type: constrains
+    from: REQ-UI-SETTINGS
+    to: FACT-UI-SUBMIT-REGION
+  - type: requires_property
+    from: REQ-UI-SETTINGS
+    to: FACT-UI-SUBMIT-POSITION
+```
+
+A later requirement writing `position: top_left` on the same subject is rejected on write.
+
+## Header item order
+
+Use one indexed `property_key` per slot against the same subject region:
+`nav_order_1: home`, `nav_order_2: search`, `nav_order_3: profile`, each as a separate
+`property_value` fact linked with `requires_property`. This makes each slot independently
+contradiction-checkable.
+
+## Relational alignment
+
+```yaml
+id: FACT-UI-NAV-ALIGN
+fact_kind: predicate
+predicate_name: visual_layout_rule
+predicate_args: [navigation_rail, aligned_with, header]
+polarity: assert
+canonical_key: visual_layout_rule(navigation_rail,aligned_with,header)
+```
+
+Link with `requires_predicate`. An `assert`/`deny` pair over the same predicate namespace,
+name, and ordered arguments is a blocking `domain-contradictions` conflict.
+
+## UI component traceability
+
+Model the component as a `symbol` with `sourceFile` and `symbol_role: behavioral`, linked
+`implements` to the requirement, so component edits surface the visual spec in impact
+diagnostics (`symbol_semantic_review_needed`).
+
+## Workflow
+
+1. `kb_semantic_advisor` on the full description; audit or supply `clauses`.
+2. Relational clauses: `kb_suggest_predicates`, apply the predicate plan and
+   `requires_predicate`.
+3. Scalar placement/alignment/order clauses: `kb_model_requirement`, apply the strict
+   subject/property plan and `constrains` / `requires_property`.
+4. Preserve `claim_key` / `claim_text`; merge every key into the requirement
+   `logic_claims` manifest.
+5. `kb_validate_upsert`, create endpoints first, then sequential `kb_upsert`.
+6. `kb_check` with `logic-coverage`, `predicate-verifiability`, `domain-contradictions`,
+   then a final unfiltered `kb_check`.
+
+Non-UI projects: declare `has_ui: false` during bootstrap and no UI entities are proposed.

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

@@ -7,9 +7,14 @@ 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
+4. **Decompose**: `kb_semantic_advisor` on the complete normative prose; verify or supply every atomic clause
+5. **Choose per-clause lanes**: strict facts for scalar claims; `kb_suggest_predicates` for approved ground ontology relations; `kb_model_requirement` with `kibi.logic.v1` for conditions, exceptions, modalities, quantifiers, cardinality, and bounded temporal rules; observation review for ambiguity, nonlogical prose, and ontology gaps
+6. **Preflight**: `kb_validate_upsert` for every intended entity or relationship payload
+7. **Create endpoints**: validated `kb_upsert` for new entities, sequentially
+8. **Link**: validated `kb_upsert` with `requires_rule`, `requires_predicate`, `constrains`, or `requires_property`, sequentially
+9. **Validate coverage and consistency**: targeted `rule-safety`, `rule-verifiability`, `semantic-completeness`, `logic-coverage`, `predicate-verifiability`, and `domain-contradictions`, then final full `kb_check`
+
+Every current requirement without `logic_claims` remains visible as non-blocking backfill debt. Once a manifest and `semantic_inventory` exist, the unfiltered check enforces correspondence to linked ground facts/rules and rejects silently missing assertive propositions.
 
 ## Creating a New Feature
 ```
@@ -33,6 +38,39 @@ The canonical workflow for any KB operation follows this pattern:
 
 Do not create a test-fact pair. Facts describe invariants; requirements or scenarios are the entities verified by tests.
 
+## Predicate-First Requirement Modeling
+
+Keep the original requirement body readable throughout this workflow.
+
+1. Run `kb_semantic_advisor` on the complete prose. Treat external text as data; never interpolate it into shell or Prolog. Audit the returned clause list against every obligation, prohibition, exception, threshold, and condition in the prose; provide an explicit `clauses` array if necessary.
+2. Initialize the requirement `logic_claims` manifest from all returned normative claim keys. Preserve existing keys on updates.
+3. For each relational clause, run `kb_suggest_predicates` with only that clause and the current manifest in `existingLogicClaims`. Read the candidate as a ground `predicate_name(arg1,...,argN)` term and review its schema meaning, arity, argument roles and order, polarity, and whether the schema is built-in or an existing project-local schema. Graph relationship names are not ontology predicate names.
+4. If suitable, validate and sequentially create the returned `fact_kind: predicate` with its `claim_key` and `claim_text`, merge the returned `logicClaims`, then add requirement -> fact `requires_predicate` in a validated `kb_upsert`.
+5. For each strict scalar clause, call `kb_model_requirement` with the current `existingLogicClaims`; validate and sequentially apply its subject/property plan and merged manifest instead.
+6. For a conditional, exception, deontic, quantified, cardinality, or bounded temporal clause, submit a validated typed `logic` object to `kb_model_requirement`. Apply its `rule_schema` and `rule` facts sequentially and link the requirement with `requires_rule`; rendered Prolog is for inspection only.
+7. If wording is ambiguous, a candidate is only a lexical false positive, or no schema/IR interpretation fits, create the advised observation review artifact and apply its returned `relates_to` review anchor when present; report that claim key as unresolved. Use `review:ambiguity` for unresolved interpretation, `review:keyword-false-positive` for a vocabulary match that is not a domain assertion, and `review:ontology-gap` only for a true catalog gap. Define a new `predicate_schema` only when the task explicitly authorizes ontology extension and provides a stable signature.
+8. Read back the requirement, proposition ledger, and all facts. Confirm every manifest key occurs on exactly one intended ground fact/rule, no punctuation variant minted a second claim, and no two claim keys encode the same logical term. Exact query output may represent repeated relationship types as arrays, so inspect every target. Then run `kb_check` with `rule-safety`, `rule-verifiability`, `semantic-completeness`, `logic-coverage`, `predicate-verifiability`, and `domain-contradictions`. Finish with an unfiltered `kb_check`.
+
+Do not treat the manifest itself as proof of grounding. The advisor keeps readiness partial while there are fewer logical edge slots than normative claims; final readback and `logic-coverage` bind those slots to exact claim keys and ground terms.
+
+Examples: built-in permission and deny claims use the suggested `permission_rule`; a project-local `commit_action` is valid only after its schema exists; session timeout is strict scalar; “better support” is ambiguous; `publishes_event` for publishing an article is a false positive; annotation anchoring without a fitting schema is an ontology gap. The authoritative payloads are in `resources/fact-lanes.md`.
+
+On resume after interruption, repeat `kb_query` for exact endpoints and apply only missing validated writes. Keep `kb_upsert` concurrency at one.
+
+## UI / Visual Requirement Modeling
+
+Optional per-project workflow for recording what the screen should look like. Non-UI projects skip this lane entirely.
+
+1. Create a prose `req` holding the full visual description; it is the searchable anchor agents discover before touching a UI file.
+2. Run `kb_semantic_advisor` on the description; audit or supply `clauses`.
+3. For relational layout clauses ("X must remain visually aligned with Y"), call `kb_suggest_predicates`, apply the returned `fact_kind: predicate` plan with `predicate_name: visual_layout_rule` and `requires_predicate`.
+4. For scalar placement, alignment, and ordering clauses, call `kb_model_requirement` and apply strict `fact_kind: subject` / `fact_kind: property_value` facts linked with `constrains` / `requires_property`. Model header order as indexed property keys (`nav_order_1`, `nav_order_2`, ...) against one subject region.
+5. Preserve `claim_key` / `claim_text` on every ground fact and merge every key into the requirement `logic_claims` manifest.
+6. Model UI components as `symbol` entities with `sourceFile` and `symbol_role: behavioral`, linked `implements` to the requirement.
+7. `kb_validate_upsert`, create endpoints first, then sequential `kb_upsert`. Run `kb_check` with `logic-coverage`, `predicate-verifiability`, and `domain-contradictions`, then a final unfiltered `kb_check`.
+
+Incompatible values on the same subject/property from two current requirements are rejected on write; change an intentional value via a replacement requirement linked with `supersedes`. Full payloads are in `resources/ui-requirements.md`.
+
 ## Fixing a Traceability Gap
 ```
 1. kb_query --sourceFile <code-file> to find linked entities

package/dist/public/skills.d.ts

@@ -1,42 +1,5 @@
-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[];
-};
+export { SkillNotFoundError, SkillOversizeError, SkillResourceNotFoundError, SkillResourceOutOfBoundsError, SkillValidationError, } from "./skill-system/errors.js";
+export { listBundledSkills, loadBundledSkill, loadBundledSkillFrom, readBundledSkillResource, readBundledSkillResourceFrom, resetBundledSkillsDir, setBundledSkillsDir, } from "./skill-system/loader.js";
+export type { SkillBundle, SkillManifest } from "./skill-system/types.js";
+export { validateSkillBundle } from "./skill-system/validation.js";
 //# sourceMappingURL=skills.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/public/skills.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,0BAA0B,EAC1B,6BAA6B,EAC7B,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,wBAAwB,EACxB,4BAA4B,EAC5B,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/public/skills.js

@@ -1,270 +1,3 @@
-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() {
-    // implements REQ-001
-    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) {
-    // implements REQ-001
-    const rootDir = findBundledSkillRoot(id);
-    if (!rootDir) {
-        throw new SkillNotFoundError(id);
-    }
-    return parseSkillBundle(rootDir);
-}
-export function readBundledSkillResource(id, resourcePath) {
-    // implements REQ-001
-    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) {
-    // implements REQ-001
-    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);
-}
+export { SkillNotFoundError, SkillOversizeError, SkillResourceNotFoundError, SkillResourceOutOfBoundsError, SkillValidationError, } from "./skill-system/errors.js";
+export { listBundledSkills, loadBundledSkill, loadBundledSkillFrom, readBundledSkillResource, readBundledSkillResourceFrom, resetBundledSkillsDir, setBundledSkillsDir, } from "./skill-system/loader.js";
+export { validateSkillBundle } from "./skill-system/validation.js";

package/dist/public/symbol-granularity.d.ts

@@ -4,6 +4,14 @@ export declare const TRACEABILITY_RELATIONSHIP_TYPES: readonly ["implements", "c
 export type TraceabilityRelationshipType = (typeof TRACEABILITY_RELATIONSHIP_TYPES)[number];
 export declare const ALLOWED_GRANULARITY_REASONS: readonly ["config-artifact", "module-level-behavior", "extractor-miss", "legacy-link"];
 export type GranularityReason = (typeof ALLOWED_GRANULARITY_REASONS)[number];
+/**
+ * Granularity reasons that document coarse file/module-level coverage for which
+ * generated per-symbol coordinates are not expected. These anchors legitimately
+ * carry no coordinate artifact entries. `legacy-link` is intentionally excluded:
+ * it is a canonical reason but still coordinates a real extractable symbol.
+ */
+export declare const COARSE_GRANULARITY_REASONS: readonly ["config-artifact", "module-level-behavior", "extractor-miss", "test-suite"];
+export type CoarseGranularityReason = (typeof COARSE_GRANULARITY_REASONS)[number];
 export type SymbolKind = "function" | "class" | "method" | "property" | "accessor" | "interface" | "type" | "variable" | "enum" | "unknown";
 export type SourceSymbolKind = SymbolKind;
 export interface GranularSymbolCandidate {
@@ -16,6 +24,7 @@ export declare const inferSymbolRoleFromKind: typeof inferSymbolRole;
 export declare function isSymbolRole(value: unknown): value is SymbolRole;
 export declare function isTraceabilityRelationshipType(value: unknown): value is TraceabilityRelationshipType;
 export declare function isAllowedGranularityReason(value: unknown): value is GranularityReason;
+export declare function isCoarseGranularityReason(value: unknown): value is CoarseGranularityReason;
 export declare function getSymbolRole(candidate: GranularSymbolCandidate): SymbolRole;
 export declare function isBehavioralSymbol(candidate: GranularSymbolCandidate): boolean;
 export declare function getBehavioralSymbolNames(candidates: GranularSymbolCandidate[]): string[];

package/dist/public/symbol-granularity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"symbol-granularity.d.ts","sourceRoot":"","sources":["../../src/public/symbol-granularity.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,YAAY,oFAOf,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,eAAO,MAAM,+BAA+B,yDAIlC,CAAC;AAEX,MAAM,MAAM,4BAA4B,GACtC,CAAC,OAAO,+BAA+B,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,eAAO,MAAM,2BAA2B,wFAK9B,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7E,MAAM,MAAM,UAAU,GAClB,UAAU,GACV,OAAO,GACP,QAAQ,GACR,UAAU,GACV,UAAU,GACV,WAAW,GACX,MAAM,GACN,UAAU,GACV,MAAM,GACN,SAAS,CAAC;AAEd,MAAM,MAAM,gBAAgB,GAAG,UAAU,CAAC;AAE1C,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB;AASD,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAgB5D;AAED,eAAO,MAAM,uBAAuB,wBAAkB,CAAC;AAEvD,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAIhE;AAED,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,4BAA4B,CAIvC;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,iBAAiB,CAE5B;AAED,wBAAgB,aAAa,CAAC,SAAS,EAAE,uBAAuB,GAAG,UAAU,CAI5E;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,uBAAuB,GACjC,OAAO,CAET;AAED,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,uBAAuB,EAAE,GACpC,MAAM,EAAE,CAMV;AAED,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,uBAAuB,EAAE,GACpC,MAAM,EAAE,CAQV"}
+{"version":3,"file":"symbol-granularity.d.ts","sourceRoot":"","sources":["../../src/public/symbol-granularity.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,YAAY,oFAOf,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,eAAO,MAAM,+BAA+B,yDAIlC,CAAC;AAEX,MAAM,MAAM,4BAA4B,GACtC,CAAC,OAAO,+BAA+B,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,eAAO,MAAM,2BAA2B,wFAK9B,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7E;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,uFAK7B,CAAC;AAEX,MAAM,MAAM,uBAAuB,GACjC,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9C,MAAM,MAAM,UAAU,GAClB,UAAU,GACV,OAAO,GACP,QAAQ,GACR,UAAU,GACV,UAAU,GACV,WAAW,GACX,MAAM,GACN,UAAU,GACV,MAAM,GACN,SAAS,CAAC;AAEd,MAAM,MAAM,gBAAgB,GAAG,UAAU,CAAC;AAE1C,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB;AAYD,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAgB5D;AAED,eAAO,MAAM,uBAAuB,wBAAkB,CAAC;AAEvD,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAIhE;AAED,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,4BAA4B,CAIvC;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,iBAAiB,CAE5B;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,uBAAuB,CAElC;AAED,wBAAgB,aAAa,CAAC,SAAS,EAAE,uBAAuB,GAAG,UAAU,CAI5E;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,uBAAuB,GACjC,OAAO,CAET;AAED,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,uBAAuB,EAAE,GACpC,MAAM,EAAE,CAMV;AAED,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,uBAAuB,EAAE,GACpC,MAAM,EAAE,CAQV"}

package/dist/public/symbol-granularity.js

@@ -17,8 +17,21 @@ export const ALLOWED_GRANULARITY_REASONS = [
     "extractor-miss",
     "legacy-link",
 ];
+/**
+ * Granularity reasons that document coarse file/module-level coverage for which
+ * generated per-symbol coordinates are not expected. These anchors legitimately
+ * carry no coordinate artifact entries. `legacy-link` is intentionally excluded:
+ * it is a canonical reason but still coordinates a real extractable symbol.
+ */
+export const COARSE_GRANULARITY_REASONS = [
+    "config-artifact",
+    "module-level-behavior",
+    "extractor-miss",
+    "test-suite",
+];
 const traceabilityRelationshipTypeSet = new Set(TRACEABILITY_RELATIONSHIP_TYPES);
 const allowedGranularityReasonSet = new Set(ALLOWED_GRANULARITY_REASONS);
+const coarseGranularityReasonSet = new Set(COARSE_GRANULARITY_REASONS);
 export function inferSymbolRole(kind) {
     switch (kind) {
         case "function":
@@ -46,6 +59,9 @@ export function isTraceabilityRelationshipType(value) {
 export function isAllowedGranularityReason(value) {
     return typeof value === "string" && allowedGranularityReasonSet.has(value);
 }
+export function isCoarseGranularityReason(value) {
+    return typeof value === "string" && coarseGranularityReasonSet.has(value);
+}
 export function getSymbolRole(candidate) {
     if (candidate.role)
         return candidate.role;

package/dist/runtime/cli-runtime.d.ts

@@ -0,0 +1,3 @@
+import type { OperationRuntime, RuntimeOptions } from "../public/operations/runtime-types.js";
+export declare function createCliRuntime(options?: RuntimeOptions): OperationRuntime;
+//# sourceMappingURL=cli-runtime.d.ts.map

package/dist/runtime/cli-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-runtime.d.ts","sourceRoot":"","sources":["../../src/runtime/cli-runtime.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAEV,gBAAgB,EAGhB,cAAc,EACf,MAAM,uCAAuC,CAAC;AAwC/C,wBAAgB,gBAAgB,CAC9B,OAAO,GAAE,cAAmB,GAC3B,gBAAgB,CAoElB"}

package/dist/runtime/cli-runtime.js

@@ -0,0 +1,96 @@
+import path from "node:path";
+import { PrologProcess } from "../prolog.js";
+import { nodeFilesystem, nodeGit, nodeNetwork, } from "../public/operations/node-ports.js";
+import { resolveActiveBranch } from "../utils/branch-resolver.js";
+function createDefaultProlog() {
+    const process = new PrologProcess({ timeout: 120_000 });
+    let lastResult = null;
+    return {
+        start: () => process.start(),
+        query: async (goal) => {
+            lastResult = await process.query(goal);
+            return lastResult;
+        },
+        nextSolution: async () => {
+            const result = lastResult;
+            lastResult = null;
+            return result;
+        },
+        save: () => process.query("kb_save"),
+        terminate: () => process.terminate(),
+    };
+}
+function workspaceRoot(options) {
+    const envRoot = process.env.KIBI_WORKSPACE ??
+        process.env.KIBI_PROJECT_ROOT ??
+        process.env.KIBI_ROOT;
+    return path.resolve(options.workspaceRoot ?? envRoot ?? process.cwd());
+}
+function quoteProlog(value) {
+    return value.replaceAll("'", "''");
+}
+// implements REQ-kibi-operation-interface-parity
+export function createCliRuntime(options = {}) {
+    const ownedPrologs = new WeakMap();
+    return {
+        open: async (spec, invocationOptions = {}) => {
+            const merged = {
+                ...options,
+                ...invocationOptions,
+            };
+            const root = workspaceRoot(merged);
+            const signal = merged.signal ?? new AbortController().signal;
+            const clock = merged.clock ?? (() => new Date());
+            const git = merged.git ?? nodeGit;
+            const contextBase = {
+                workspaceRoot: root,
+                signal,
+                clock,
+                fs: merged.fs ?? nodeFilesystem,
+                git,
+                net: merged.net ?? nodeNetwork,
+            };
+            if (!spec.requiresProlog) {
+                return contextBase;
+            }
+            const prolog = merged.prolog ?? createDefaultProlog();
+            try {
+                await prolog.start?.();
+                let branch = process.env.KIBI_BRANCH?.trim();
+                if (!branch) {
+                    const resolved = resolveActiveBranch(root);
+                    if ("error" in resolved) {
+                        const isNonGitContext = resolved.code === "NOT_A_GIT_REPO" ||
+                            resolved.code === "GIT_NOT_AVAILABLE";
+                        if (isNonGitContext) {
+                            branch = "main";
+                        }
+                        else {
+                            throw new Error(`Failed to resolve active branch: ${resolved.error}`);
+                        }
+                    }
+                    else {
+                        branch = resolved.branch;
+                    }
+                }
+                const kbPath = path.join(root, ".kb", "branches", branch);
+                const attached = await prolog.query(`kb_attach('${quoteProlog(kbPath)}')`);
+                if (!attached.success) {
+                    throw new Error(attached.error ?? "Failed to attach branch KB");
+                }
+                const context = { ...contextBase, prolog };
+                ownedPrologs.set(context, prolog);
+                return context;
+            }
+            catch (error) {
+                await prolog.terminate?.();
+                throw error;
+            }
+        },
+        afterSuccess: async () => undefined,
+        close: async (context) => {
+            await ownedPrologs.get(context)?.terminate?.();
+            ownedPrologs.delete(context);
+        },
+    };
+}