kibi-cli 0.18.1 → 1.0.1

package/dist/public/operations/symbol-repair-plan.js

@@ -0,0 +1,123 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { analyzeSourceText } from "../../extractors/symbols-coordinator.js";
+import { loadEntities } from "./discovery-entities.js";
+export const SYMBOL_REPAIR_PLAN_VERSION = "kibi.symbol-repair-plan.v1";
+function sourceFileOf(entity) {
+    const value = entity.sourceFile ?? entity.source;
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function coordinatesPresent(entity) {
+    return [
+        entity.sourceLine,
+        entity.sourceColumn,
+        entity.sourceEndLine,
+        entity.sourceEndColumn,
+    ].every((value) => Number.isInteger(value) && Number(value) >= 0);
+}
+function currentCandidates(entity, symbols, extractedByPath) {
+    const title = typeof entity.title === "string" ? entity.title : "";
+    const kind = typeof entity.symbol_kind === "string" ? entity.symbol_kind : "";
+    const source = sourceFileOf(entity);
+    const extracted = source ? (extractedByPath.get(source) ?? []) : [];
+    const names = new Set(extracted
+        .filter((candidate) => !kind || candidate.kind === kind)
+        .map((candidate) => candidate.name));
+    return symbols
+        .filter((candidate) => candidate.id !== entity.id)
+        .filter((candidate) => {
+        const candidateTitle = typeof candidate.title === "string" ? candidate.title : "";
+        const candidateKind = typeof candidate.symbol_kind === "string" ? candidate.symbol_kind : "";
+        return ((title !== "" && candidateTitle === title) ||
+            (kind !== "" && candidateKind === kind && names.has(candidateTitle)));
+    })
+        .map((candidate) => ({
+        symbolId: String(candidate.id),
+        title: candidate.title,
+        symbolKind: candidate.symbol_kind,
+        sourceFile: sourceFileOf(candidate),
+        evidence: "current extraction/title/kind match",
+    }));
+}
+/** Build review-only, evidence-backed symbol recovery suggestions. */
+export async function buildSymbolRepairPlan(rows, context) {
+    if (!context.prolog || rows.length === 0)
+        return undefined;
+    const symbols = await loadEntities(context.prolog, { type: "symbol" });
+    const extractedByPath = new Map();
+    for (const symbol of symbols) {
+        const source = sourceFileOf(symbol);
+        if (!source || extractedByPath.has(source))
+            continue;
+        const absolute = path.isAbsolute(source)
+            ? source
+            : path.resolve(context.workspaceRoot, source);
+        if (!existsSync(absolute))
+            continue;
+        try {
+            const analysis = analyzeSourceText(absolute, readFileSync(absolute, "utf8"));
+            extractedByPath.set(source, analysis.symbols.map((candidate) => ({
+                name: candidate.name,
+                kind: candidate.kind,
+            })));
+        }
+        catch {
+            extractedByPath.set(source, []);
+        }
+    }
+    const repairs = rows.flatMap((row) => {
+        if (row.type !== "symbol")
+            return [];
+        const entity = symbols.find((candidate) => candidate.id === row.id);
+        if (!entity)
+            return [];
+        const source = sourceFileOf(entity);
+        const absolute = source
+            ? path.isAbsolute(source)
+                ? source
+                : path.resolve(context.workspaceRoot, source)
+            : null;
+        const exists = absolute !== null && existsSync(absolute);
+        const candidates = currentCandidates(entity, symbols, extractedByPath);
+        const extraction = source ? extractedByPath.get(source) : undefined;
+        const extractionProvesAbsent = exists &&
+            extraction !== undefined &&
+            !extraction.some((candidate) => candidate.name === entity.title &&
+                (!entity.symbol_kind || candidate.kind === entity.symbol_kind));
+        const gaps = Array.isArray(row.gaps) ? row.gaps.map(String) : [];
+        const action = !exists
+            ? entity.symbol_origin === "extracted"
+                ? "delete_obsolete_symbol"
+                : "review"
+            : extractionProvesAbsent && entity.symbol_origin === "extracted"
+                ? "delete_obsolete_symbol"
+                : !coordinatesPresent(entity)
+                    ? "refresh_coordinates"
+                    : candidates.length > 0
+                        ? "remap"
+                        : "review";
+        return [
+            {
+                symbolId: String(entity.id),
+                action,
+                candidates,
+                evidence: {
+                    sourceFile: source,
+                    sourceExists: exists,
+                    extractionProvesAbsent,
+                    gaps,
+                    currentExtractionAvailable: source
+                        ? extractedByPath.has(source)
+                        : false,
+                    autoApply: false,
+                },
+            },
+        ];
+    });
+    return {
+        version: SYMBOL_REPAIR_PLAN_VERSION,
+        readOnly: true,
+        autoApplicable: false,
+        repairs,
+    };
+}

package/dist/public/operations/types.d.ts

@@ -1,7 +1,14 @@
 import type { OperationContext } from "./runtime-types.js";
 export type { OperationContext };
-export type OperationName = "kb_query" | "kb_search" | "kb_status" | "kb_skills_list" | "kb_skills_load" | "kb_skills_read" | "kb_find_gaps" | "kb_coverage" | "kb_graph" | "kb_sparql_remote" | "kb_semantic_advisor" | "kb_upsert" | "kb_validate_upsert" | "kb_delete" | "kb_check" | "kb_model_requirement" | "kb_suggest_predicates" | "kb_autopilot_generate";
+export type OperationName = "kb_query" | "kb_search" | "kb_status" | "kb_skills_list" | "kb_skills_load" | "kb_skills_read" | "kb_find_gaps" | "kb_coverage" | "kb_graph" | "kb_sparql_remote" | "kb_semantic_advisor" | "kb_upsert" | "kb_validate_upsert" | "kb_delete" | "kb_check" | "kb_model_requirement" | "kb_suggest_predicates" | "kb_plan_bootstrap" | "kb_compile_intent" | "kb_apply_plan" | "kb_ingest_verification";
 export type OperationEffect = "local-read" | "kb-read" | "workspace-read" | "network-read" | "kb-write" | "workspace-write";
+export type OperationEffectDeclaration = Readonly<{
+    kind: OperationEffect;
+    mutability: "read" | "write";
+    destructive: boolean;
+    retrySafety: "safe" | "unsafe";
+    openWorld: boolean;
+}>;
 export interface OperationContent {
     readonly type: string;
     readonly text?: string;
@@ -10,6 +17,38 @@ export interface OperationResult<O = unknown> {
     readonly content: readonly OperationContent[];
     readonly structuredContent?: O;
 }
+export type KibiResultStatus = "success" | "committed_with_repairs" | "error";
+export type KibiResult<T = unknown> = {
+    readonly kibiProtocol: 1;
+    readonly operation: OperationName | string;
+    readonly resultVersion: string;
+    readonly status: KibiResultStatus;
+    readonly data: T;
+    readonly effects: readonly {
+        readonly kind: string;
+        readonly status: "completed" | "failed" | "not_applicable";
+        readonly detail?: unknown;
+        readonly errorCode?: string;
+    }[];
+    readonly diagnostics: readonly {
+        readonly code?: string;
+        readonly severity?: "info" | "warning" | "error";
+        readonly message: string;
+        readonly detail?: unknown;
+    }[];
+    readonly nextActions: readonly {
+        readonly operation: OperationName | string;
+        readonly input?: unknown;
+        readonly reason: string;
+        readonly required: boolean;
+    }[];
+    readonly error?: {
+        readonly code: string;
+        readonly message: string;
+        readonly retryable: boolean;
+        readonly details?: unknown;
+    };
+};
 export interface OperationSpec<I = Readonly<Record<string, unknown>>, O = unknown> {
     readonly name: OperationName;
     readonly cliName: string;
@@ -17,8 +56,20 @@ export interface OperationSpec<I = Readonly<Record<string, unknown>>, O = unknow
     readonly businessInputSchema: Readonly<Record<string, unknown>>;
     readonly requiresProlog: boolean;
     readonly effects: readonly OperationEffect[];
+    /** Generated effect metadata used by MCP annotations and telemetry. */
+    readonly declaredEffects?: readonly OperationEffectDeclaration[];
+    /** Version of the machine-readable result data for this operation. */
+    readonly resultVersion?: string;
+    /** JSON Schema for the machine-readable result data. */
+    readonly outputSchema?: Readonly<Record<string, unknown>>;
     readonly execute: {
         bivarianceHack(input: I, context: OperationContext): Promise<OperationResult<O>>;
     }["bivarianceHack"];
 }
+/** A catalog spec after its generated machine contract has been attached. */
+export type ResolvedOperationSpec<I = Readonly<Record<string, unknown>>, O = unknown> = OperationSpec<I, O> & {
+    readonly declaredEffects: readonly OperationEffectDeclaration[];
+    readonly resultVersion: string;
+    readonly outputSchema: Readonly<Record<string, unknown>>;
+};
 //# sourceMappingURL=types.d.ts.map

package/dist/public/operations/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/public/operations/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,YAAY,EAAE,gBAAgB,EAAE,CAAC;AACjC,MAAM,MAAM,aAAa,GACrB,UAAU,GACV,WAAW,GACX,WAAW,GACX,gBAAgB,GAChB,gBAAgB,GAChB,gBAAgB,GAChB,cAAc,GACd,aAAa,GACb,UAAU,GACV,kBAAkB,GAClB,qBAAqB,GACrB,WAAW,GACX,oBAAoB,GACpB,WAAW,GACX,UAAU,GACV,sBAAsB,GACtB,uBAAuB,GACvB,uBAAuB,CAAC;AAE5B,MAAM,MAAM,eAAe,GACvB,YAAY,GACZ,SAAS,GACT,gBAAgB,GAChB,cAAc,GACd,UAAU,GACV,iBAAiB,CAAC;AAEtB,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,OAAO;IAC1C,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC9C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,aAAa,CAC5B,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACrC,CAAC,GAAG,OAAO;IAEX,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAChE,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,QAAQ,CAAC,OAAO,EAAE;QAChB,cAAc,CACZ,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;KAChC,CAAC,gBAAgB,CAAC,CAAC;CACrB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/public/operations/types.ts"],"names":[],"mappings":"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"}

package/dist/public/playwright-case-id.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Stable identity for a statically named Playwright test case.
+ * The path is always repository-relative before hashing so the same case has
+ * the same identity in a checkout, packed consumer, and dogfood workspace.
+ */
+export declare function playwrightCaseId(sourceFile: string, qualifiedTitle: string): string;
+export declare function normalizePlaywrightSourceFile(sourceFile: string, workspaceRoot?: string): string;
+//# sourceMappingURL=playwright-case-id.d.ts.map

package/dist/public/playwright-case-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright-case-id.d.ts","sourceRoot":"","sources":["../../src/public/playwright-case-id.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AAEH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,GACrB,MAAM,CAOR;AAGD,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,MAAM,EAClB,aAAa,CAAC,EAAE,MAAM,GACrB,MAAM,CASR"}

package/dist/public/playwright-case-id.js

@@ -0,0 +1,25 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+/**
+ * Stable identity for a statically named Playwright test case.
+ * The path is always repository-relative before hashing so the same case has
+ * the same identity in a checkout, packed consumer, and dogfood workspace.
+ */
+// implements REQ-kibi-verification-evidence-contract
+export function playwrightCaseId(sourceFile, qualifiedTitle) {
+    const normalizedPath = sourceFile
+        .replaceAll("\\", "/")
+        .replace(/^\.\//, "")
+        .replace(/^\/+/, "");
+    const key = `${normalizedPath}\0${qualifiedTitle.trim()}`;
+    return `SYM-PW-${createHash("sha256").update(key).digest("hex").slice(0, 16).toUpperCase()}`;
+}
+// implements REQ-kibi-verification-evidence-contract
+export function normalizePlaywrightSourceFile(sourceFile, workspaceRoot) {
+    const absolute = path.resolve(sourceFile);
+    if (!workspaceRoot)
+        return sourceFile.replaceAll("\\", "/");
+    const root = path.resolve(workspaceRoot);
+    const relative = path.relative(root, absolute);
+    return (relative.startsWith("..") ? sourceFile : relative).replaceAll("\\", "/");
+}

package/dist/public/schemas/entity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../../src/public/schemas/entity.ts"],"names":[],"mappings":"AAwTA,QAAA,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CA6TzC,CAAC;AAEF,eAAe,YAAY,CAAC"}
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../../src/public/schemas/entity.ts"],"names":[],"mappings":"AA2TA,QAAA,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CA+TzC,CAAC;AAEF,eAAe,YAAY,CAAC"}

package/dist/public/schemas/entity.js

@@ -17,7 +17,7 @@
  */
 // Typed fact field enums per proposal
 import { SYMBOL_ROLES } from "../symbol-granularity.js";
-import { VERIFICATION_RECEIPT_SCHEMA } from "../verification-receipt.js";
+import { VERIFICATION_CONTRACT_SCHEMA, VERIFICATION_RECEIPT_SCHEMA, } from "../verification-receipt.js";
 const factConditionals = JSON.parse(`[
   {
     "if": {
@@ -416,6 +416,7 @@ const entitySchema = {
                 "module-level-behavior",
                 "extractor-miss",
                 "legacy-link",
+                "test-suite",
             ],
         },
         symbol_role: {
@@ -430,9 +431,9 @@ const entitySchema = {
             type: "string",
             enum: ["internal", "consumer"],
         },
+        verification_contract: VERIFICATION_CONTRACT_SCHEMA,
         verification_receipts: {
             type: "array",
-            maxItems: 50,
             items: VERIFICATION_RECEIPT_SCHEMA,
         },
         type: {
@@ -574,6 +575,7 @@ const entitySchema = {
                     anyOf: [
                         { required: ["verification_scope"] },
                         { required: ["verification_perspective"] },
+                        { required: ["verification_contract"] },
                         { required: ["verification_receipts"] },
                     ],
                 },

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

@@ -0,0 +1,58 @@
+---
+id: kibi-bootstrap
+name: kibi-bootstrap
+description: Bootstrap Kibi from the current Git checkout with exact Git attachment, preview approval, source-first writes, and repair-safe completion.
+version: 3.0.0
+kibiCompatibility: ">=1.0.0"
+tags:
+  - kibi
+  - bootstrap
+  - source-first
+  - agent-guidance
+resources:
+  - resources/bootstrap.md
+  - resources/branch-lifecycle.md
+  - resources/source-authoring.md
+  - resources/operation-access.md
+---
+## Goal
+
+Seed branch-local Kibi knowledge for an attached but thin repository without
+creating a parallel human-maintained ticket system. Ask at most four bounded
+context questions only when the planner says repository evidence is
+insufficient; agents own deterministic translation and humans resolve genuine
+ambiguity. A seeded repository hands off to the normal Kibi workflow.
+
+## Interface and preview
+
+Use the visible approved MCP surface or the trusted project-local CLI as equal
+peer interfaces. If neither is available, stop. Run `kb_plan_bootstrap` (or
+`plan-bootstrap --input`) read-only. If it returns `needs_context`, ask only its
+bounded questions (never more than four), then rerun the planner. Show the
+complete returned `structuredContent.plan`, including its canonical hash, and
+get explicit approval before any write. Pass that plan object unchanged to
+`kb_apply_plan`; do not reconstruct it from preview fields.
+
+For CLI JSON, use the trusted route with `--input` (for example
+`printf '%s\n' '{}' | kibi status --input -`); MCP and CLI are semantic peers.
+Read the branch-lifecycle and source-authoring resources before migration,
+source writes, or repair actions.
+
+## Apply and verify
+
+Apply the approved `kibi.bootstrap-plan.v1` by calling `kb_apply_plan` with the
+exact plan and approved hash. The operation owns dependency ordering,
+source-first writes, sequential mutation, and recovery journaling. Direct
+`kb_upsert` is forbidden for every kibi-bootstrap task, including after
+approval; never replay plan actions manually. Use `kb_delete` only for an
+approved hash-bound deletion plan; evolve requirements with `supersedes`.
+Finish with `kb_check` and `kb_status`.
+
+Consume the versioned `kibiProtocol: 1` result envelope: inspect `status`, `effects`,
+`diagnostics`, and `nextActions`. On `committed_with_repairs`, execute required
+repair actions and never retry the original mutation.
+
+Kibi may author tracked Markdown/YAML/manifests and relationship shards
+transactionally, but never Git-stages or commits them. Never read or edit
+`.kb` directly. Missing exact branch stores are compiled from this checkout's
+tracked sources by `kibi sync`; Kibi does not copy another branch's store.

package/dist/public/skills/kibi-bootstrap/resources/bootstrap.md

@@ -0,0 +1,11 @@
+# Bootstrap resource
+
+`kb_plan_bootstrap` is read-only and returns `kibi.bootstrap-plan.v1`. Review
+candidate evidence, exact actions, dependencies, expected snapshots, source
+hashes, bounded questions, diagnostics, and the canonical `planHash` before
+approving. A preview does not authorize source edits. After approval, pass the
+unchanged returned `structuredContent.plan` to `kb_apply_plan` once with its
+approved hash; inspect its typed result
+and follow `nextActions` if it returns `committed_with_repairs`. Direct
+`kb_upsert` is forbidden for every bootstrap task; never manually replay the
+plan through it.

package/dist/public/skills/kibi-bootstrap/resources/branch-lifecycle.md

@@ -0,0 +1,7 @@
+# Branch lifecycle
+
+Use the exact `KIBI_BRANCH` value or Git symbolic HEAD. Hashed stores carry a
+matching `branch.json`; missing stores are compiled from tracked sources by
+`kibi sync`. Legacy literal stores require explicit migration. Kibi never
+copies stores between branches or resolves Git conflicts. Read the preview,
+approval hash, quarantine, restore, and purge details before lifecycle work.

package/dist/public/skills/kibi-bootstrap/resources/operation-access.md

@@ -0,0 +1,5 @@
+# Operation access
+
+MCP tools and the trusted project-local CLI are peer surfaces for the same
+operation contracts. Use the dedicated JSON route; parse the shared
+`KibiResult` envelope and follow required `nextActions` after partial commits.

package/dist/public/skills/kibi-bootstrap/resources/source-authoring.md

@@ -0,0 +1,8 @@
+# Source authoring
+
+Tracked documents, manifests, and relationship shards are authoritative.
+Kibi may write them transactionally but does not stage or commit them. Use
+`document.path` for ambiguous new targets, preserve existing bodies when the
+body is omitted, and use hash-bound deletion plans. On
+`committed_with_repairs`, follow typed `nextActions` and never retry the
+original mutation.

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

@@ -1,14 +1,18 @@
 ---
 id: kibi-freshness
 name: kibi-freshness
-description: Check branch freshness and source linkage quality before decisions or risky writes.
-version: 1.0.0
-kibiCompatibility: "*"
+description: Check exact Git attachment, branch migration/quarantine, compiled-store freshness, source linkage, and repair state before decisions or writes.
+version: 2.0.0
+kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
   - mcp
   - freshness
   - agent-guidance
+resources:
+  - resources/branch-lifecycle.md
+  - resources/source-authoring.md
+  - resources/operation-access.md
 ---
 ## Goal
 
@@ -16,10 +20,10 @@ Help agents decide whether Kibi knowledge is current enough to support safe chan
 
 ## Interface Selection
 
-1. If Kibi MCP tools are visible and approved for the workspace, use the MCP surface only.
-2. Otherwise, in a trusted workspace, use the canonical project-local CLI fallback through `npx --no-install kibi ...` or `bunx --no-install kibi ...`.
-3. If the project-local CLI is unavailable or too old, stop and tell the operator to enable or install Kibi.
-4. Never use a global fallback or an installing runner.
+1. Use whichever approved peer is visible: MCP or the trusted project-local CLI.
+2. They have the same operation semantics and machine envelope; neither is preferred.
+3. If neither surface is available, stop and tell the operator which capability must be enabled.
+4. Never install packages, choose a package manager, or use a global fallback as part of freshness inspection.
 
 Use `kibi-usage/resources/operation-access.md` for exact dedicated routes. A project-local CLI freshness check is executable as:
 
@@ -30,15 +34,41 @@ echo '{}' | npx --no-install kibi status --input -
 ## Capability Workflow
 
 - Use `kb_status`, or `status --input`, first to confirm branch attachment, freshness state, dirty-worktree evidence, and whether the knowledge snapshot is safe to rely on.
+- Treat `branchAttachment.gitBranch`, `branchAttachment.kbBranch`, and
+  `branchAttachment.storePath` as exact identities. Hashed stores require a
+  matching `branch.json`; a `legacy_compat` attachment is read-only until an
+  explicit old/new migration is approved.
+- Inspect bounded `staleReasons` (indexed source missing/newer or documentation
+  source newer) and `verificationSnapshotChanges`. Kibi deliberately reports
+  editor/config paths such as editor dot-directories; do not silently ignore them.
 - Use `kb_query`, or `query --input`, with `sourceFile` and text references for source-linked discovery.
 - Re-run `kb_search`, or `search --input`, after sync gaps or stale context are detected.
 - If knowledge must change, use the selected interface's `kb_upsert`/`upsert` or `kb_delete`/`delete` operation sequentially, then finish with `kb_check`/`check`.
+- If status returns `migrationPlan.version: kibi.migration-plan.v2`, inspect its
+  hash, scope, dependencies, and safety classes. Apply only ready automatic
+  actions with explicit hash/action approval through `kb_apply_plan` or
+  `kibi migrate --apply-safe`; escalate operator actions and never infer a
+  migration from prose suggestions.
+- Parse the outer `kibiProtocol`/`resultVersion` envelope. If a mutation returns
+  `committed_with_repairs`, follow required typed `nextActions`; never retry the
+  original operation.
 
 ## Guidance
 
-- Prefer the public Kibi MCP surface whenever it is available and approved.
-- Never proceed with broad changes when freshness is stale and unresolved.
+- Treat MCP and the trusted project-local CLI as equal peer surfaces.
+- Report task outcome separately from KB, verification, proof, and limitation
+  state. A maintenance task can be complete with stale KB state or unresolved
+  proof only when its scoped objective is complete and the status is named
+  accurately; never call the KB clean/fresh in that case.
+- A legacy attachment blocks mutation, and a dirty verification snapshot blocks
+  evidence-dependent closeout. Name the exact paths/symbol IDs and whether the
+  result is fixed, accepted, or deferred.
 - If entities look stale, refresh context through an approved Kibi capability and then re-query.
 - Preserve source-file traceability by carrying `sourceFile`, text references, and validation evidence through discovery, mutation, and completion.
 - Do not read or edit files inside `.kb` directly; use the selected Kibi interface instead.
-- Completion must state one freshness outcome: KB updated, no KB impact with rationale, or deferred/failed.
+- Kibi authors tracked files but never Git-stages or commits them; ordinary Git workflows remain responsible for review and commit.
+- Completion must state one freshness outcome: KB updated, no KB impact with rationale, or deferred/failed.
+
+For exact branch lifecycle, quarantine, restore, and source-first writes, read
+the shared `kibi-usage/resources/branch-lifecycle.md` and
+`source-authoring.md` resources.

package/dist/public/skills/kibi-freshness/resources/branch-lifecycle.md

@@ -0,0 +1,7 @@
+# Branch lifecycle
+
+Use the exact `KIBI_BRANCH` value or Git symbolic HEAD. Hashed stores carry a
+matching `branch.json`; missing stores are rebuilt from tracked sources by
+`kibi sync`. Legacy literal stores require explicit migration. Kibi never copies
+stores between branches or resolves Git conflicts.
+

package/dist/public/skills/kibi-freshness/resources/operation-access.md

@@ -0,0 +1,6 @@
+# Operation access
+
+Use visible approved MCP or the trusted project-local CLI. `kb_status`/`status`
+is read-only and returns the shared versioned result envelope with exact branch,
+store, freshness, effects, diagnostics, and typed next actions.
+

package/dist/public/skills/kibi-freshness/resources/source-authoring.md

@@ -0,0 +1,7 @@
+# Source authoring
+
+Tracked documents and relationship shards are authoritative. Kibi may write
+them transactionally but does not stage or commit them. Inspect `effects` and
+typed `nextActions`; after `committed_with_repairs`, repair without retrying the
+original mutation.
+

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

@@ -1,60 +1,60 @@
 ---
 id: kibi-traceability
 name: kibi-traceability
-description: Maintain requirement, scenario, and test traceability through Kibi MCP tools.
-version: 1.0.0
-kibiCompatibility: "*"
+description: Maintain source-first requirement, scenario, test, symbol, and proof traceability through Kibi's peer interfaces.
+version: 2.0.0
+kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
-  - mcp
   - traceability
+  - source-first
+  - proof
   - agent-guidance
+resources:
+  - resources/traceability.md
+  - resources/branch-lifecycle.md
+  - resources/source-authoring.md
+  - resources/operation-access.md
 ---
 ## Goal
 
-Validate and strengthen requirement, scenario, test, behavioral-symbol, and source-file traceability before and after code changes.
+Keep product intent connected to implementation without a parallel ticket
+bureaucracy. Requirements own symbols, requirements have clause-complete
+semantics, scenarios have tests, and proof-bearing tests have fresh evidence.
 
 ## Interface Selection
 
-1. If Kibi MCP tools are visible and approved, use the MCP surface as the primary authority.
-2. Otherwise, in a trusted workspace, use the canonical project-local CLI fallback through `npx --no-install kibi ...` or `bunx --no-install kibi ...`.
-3. If neither approved MCP tools nor the project-local CLI are available, or if the CLI is unavailable or too old, stop and tell the operator to enable or install Kibi.
-4. Never use a global fallback or an installing runner.
-
-Use MCP routes for modeling, querying, checking, validation, and cleanup. Use the project-local CLI only as the fallback interface, passing JSON input through stdin. Example:
-
-```bash
-echo '{"sourceFiles":["src/auth/login.ts"],"includeImpactDiagnostics":true,"includeWorkingTreeDiff":true}' | npx --no-install kibi check --input -
-```
-
-## Capability Workflow
-
-- Locate requirements through `kb_search` or `search --input`, then inspect exact records through `kb_query` or `query --input`.
-- Before meaningful edits, identify linked requirements, scenarios, tests, facts, source files, and behavioral symbols relevant to the planned change.
-- After meaningful source edits, run `kb_check({sourceFiles:[...], includeImpactDiagnostics:true, includeWorkingTreeDiff:true})` or the equivalent `check --input` JSON recipe before deciding whether traceability is current.
-- Apply traceability updates sequentially through `kb_upsert` or `upsert --input` for requirements, scenarios, tests, facts, behavioral symbols, and source-linked relationships.
-- Validate constraints and consistency through `kb_check` or `check --input` after updates.
-- Run `kb_coverage` by requirement after validation. Treat `coverageStatus` as structural compatibility only; use the separate `proofStatus`, `proofStages`, `proofGaps`, and ranked `proofRepairs` to decide whether the complete intent-to-code chain is proven.
-- Use `kb_delete` or `delete --input` only for explicit cleanup of obsolete records or relationships.
-
-## Guidance
-
-- Prefer source-linked relationships so requirements, scenarios, tests, symbols, and files can be traced cleanly.
-- Preserve source-file traceability whenever adding or changing requirements, scenarios, tests, facts, behavioral symbols, or implementation links.
-- Preserve the canonical chain `REQ-* -> SCEN-* -> TEST-*` when adding or changing requirements.
-- Production symbols should implement requirements; test symbols should remain executable evidence for tests.
-- A proof-bearing test must be reached through the requirement's scenario, declare `verification_scope: end_to_end`, and carry a fresh passed `kibi.verification-receipt.v1` bound to the live `verificationSnapshot`. Link its executable code with `executable_for`; link each production symbol with `implements` and `covered_by` to that qualifying test. Durable `status: passing` is structural metadata, not execution proof.
-- Read `kb_status` immediately before a proof-bearing run, execute the exact recorded command, then append—not replace—the receipt history with test ID, scope, runner, command, snapshot, environment hash, timestamps, outcome, and artifact digest. Re-read coverage; wrong-snapshot, stale, failed, malformed, future-dated, or unavailable evidence must remain a gap.
-- A green structural count is not proof. Do not report success while a proposition is absent or unresolved, grounding is incomplete or non-bijective, contradiction analysis is incomplete, the E2E path is direct-only, its execution receipt is not fresh for the live snapshot, or proof-bearing symbols lack current generated coordinates.
-- Use `kb_coverage.repairPlan` to turn row-local `proofRepairs` into small dependency-ordered batches. Require `scope.complete: true` before treating it as a project-wide inventory, apply only `state: ready` work, and treat every `autoApplicable: false` batch as reviewed guidance rather than an executable mutation payload. Query current endpoints, follow its validation policy, keep upserts sequential, then rerun coverage after each batch; newly visible downstream gaps supersede the older plan. Never reinterpret `no_conflict_found` as universal consistency; it only describes the modeled ground claims Kibi could inspect.
-- When `.kb/usage.log` exists, run `kibi usage-metrics --format json --require-acceptance` after the final complete coverage call. A successful graph check does not override failed or insufficient `kibi.telemetry-acceptance.v1` evidence; follow ranked telemetry diagnostics for advisor/preflight bypasses, lookup misses, stalled proof recovery, receipt freshness, or repeated mutation failures.
-- Resolve impact at behavioral-symbol granularity when Kibi reports symbol-level diagnostics; avoid treating a whole file as impacted when the report identifies narrower linked behavior.
-- Treat `symbol_semantic_review_needed` as a prompt to inspect linked requirements and tests; Kibi reports graph links but does not prove prose semantics.
-- Do not read or edit files inside `.kb` directly; all modeling and cleanup goes through the selected Kibi interface.
-- Keep approval boundaries intact: only use Kibi MCP tools that are visible and approved, and only use the project-local CLI fallback in a trusted workspace.
-
-Public training trajectories:
-[{"taskId":"kibi-traceability-requirement-discovery-train-1","family":"requirement-discovery","reflection":"Discover the requirement linked to the supplied source symbol. This is train case 1; use only the public Kibi MCP surface."},{"taskId":"kibi-traceability-requirement-discovery-train-2","family":"requirement-discovery","reflection":"Discover the requirement linked to the supplied source symbol. This is train case 2; use only the public Kibi MCP surface."},{"taskId":"kibi-traceability-symbol-impact-granularity-train-1","family":"symbol-impact-granularity","reflection":"Resolve impact at behavioral symbol granularity rather than file granularity. This is train case 1; use only the public Kibi MCP surface."},{"taskId":"kibi-traceability-symbol-impact-granularity-train-2","family":"symbol-impact-granularity","reflection":"Resolve impact at behavioral symbol granularity rather than file granularity. This is train case 2; use only the public Kibi MCP surface."},{"taskId":"kibi-traceability-relationship-chain-train-1","family":"relationship-chain","reflection":"Trace the requirement, scenario, and test relationship chain. This is train case 1; use only the public Kibi MCP surface."},{"taskId":"kibi-traceability-relationship-chain-train-2","family":"relationship-chain","reflection":"Trace the requirement, scenario, and test relationship chain. This is train case 2; use only the public Kibi MCP surface."},{"taskId":"kibi-traceability-executable-coverage-train-1","family":"executable-coverage","reflection":"Establish executable test identity and behavioral coverage links. This is train case 1; use only the public Kibi MCP surface."},{"taskId":"kibi-traceability-executable-coverage-train-2","family":"executable-coverage","reflection":"Establish executable test identity and behavioral coverage links. This is train case 2; use only the public Kibi MCP surface."}]
-
-Previous development gate:
-{"mean":0,"hardPasses":0,"worstFamilyMean":0}
+Use the visible approved MCP tools or trusted project-local CLI as equal peer
+interfaces. Select the surface by capability; neither is semantically preferred.
+For CLI JSON, use a dedicated route such as
+`printf '%s\n' '{}' | kibi status --input -`.
+
+## Workflow
+
+Use the visible approved MCP tools or trusted project-local CLI as equal peer
+interfaces. Discover with `kb_search`, exact-filter with `kb_query`, and inspect
+`kb_status` before branch-sensitive work. Preserve `REQ-* -> SCEN-* -> TEST-*`;
+link production symbols with `implements` and qualifying tests with
+`executable_for`/`covered_by`.
+
+After source edits, run targeted `kb_check` with impact diagnostics, update
+tracked Markdown/YAML/manifests and canonical relationship shards through
+sequential `kb_upsert`, then run final check and coverage. Kibi authors tracked
+files transactionally but never Git-stages or commits them. Do not read or edit
+`.kb` directly.
+
+Use `kb_delete` only for intentional cleanup. Authored entity deletion returns a
+hash-bound approval plan; requirements normally evolve through a new
+requirement linked with `supersedes`. Relationship deletes patch shards while
+preserving unrelated records.
+
+## Typed recovery and proof
+
+Parse `kibiProtocol`, `resultVersion`, `status`, `effects`, diagnostics, and
+typed `nextActions`. On `committed_with_repairs`, execute the required repair
+action and never retry the original mutation. Keep ontology gaps, ambiguity,
+stale snapshots, unavailable receipts, and incomplete grounding explicit.
+
+Fresh proof requires a current verification snapshot, the exact contracted E2E
+command, an append-only receipt, and current symbol coordinates. Structural
+coverage and a green check are not proof by themselves.

package/dist/public/skills/kibi-traceability/resources/branch-lifecycle.md

@@ -0,0 +1,7 @@
+# Branch lifecycle
+
+The exact Git ref is the branch identity. Hashed stores are rebuildable
+artifacts, missing stores compile from this checkout, and Git remains the sole
+merge/conflict authority. Explicitly migrate legacy literal stores; do not copy
+another branch's compiled state.
+

package/dist/public/skills/kibi-traceability/resources/operation-access.md

@@ -0,0 +1,5 @@
+# Operation access
+
+Use the shared operation contracts through approved MCP or the trusted project-local
+CLI. Parse `kibiProtocol`, `resultVersion`, `status`, `effects`, diagnostics,
+and typed `nextActions`; do not retry a mutation after authoritative commit.