kibi-cli 0.19.0 → 2.0.0

package/dist/public/schemas/entity.js

@@ -15,9 +15,10 @@
  You should have received a copy of the GNU Affero General Public License
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
+import { PROOF_BINDINGS_SCHEMA, PROOF_CONTRACT_SCHEMA, } from "../proof-protocol.js";
+import { PROOF_RECEIPT_SCHEMA } from "../proof-receipt.js";
 // Typed fact field enums per proposal
 import { SYMBOL_ROLES } from "../symbol-granularity.js";
-import { VERIFICATION_RECEIPT_SCHEMA } from "../verification-receipt.js";
 const factConditionals = JSON.parse(`[
   {
     "if": {
@@ -334,6 +335,15 @@ const entitySchema = {
         severity: { type: "string" },
         links: { type: "array", items: { type: "string" } },
         text_ref: { type: "string" },
+        proof_exempt: {
+            type: "boolean",
+            description: "Requirement-only. Marks a current requirement as intentionally outside E2E-proof scope; requires proof_exempt_reason.",
+        },
+        proof_exempt_reason: {
+            type: "string",
+            minLength: 1,
+            description: "Requirement-only. Required when proof_exempt is true; surfaces as the applicability reason in coverage rows.",
+        },
         semantic_text: {
             type: "string",
             description: "Requirement-only authored prose whose exact UTF-8 bytes anchor the semantic inventory without replacing text_ref evidence.",
@@ -416,6 +426,7 @@ const entitySchema = {
                 "module-level-behavior",
                 "extractor-miss",
                 "legacy-link",
+                "test-suite",
             ],
         },
         symbol_role: {
@@ -430,10 +441,11 @@ const entitySchema = {
             type: "string",
             enum: ["internal", "consumer"],
         },
-        verification_receipts: {
+        proof_contract: PROOF_CONTRACT_SCHEMA,
+        proof_bindings: PROOF_BINDINGS_SCHEMA,
+        proof_receipts: {
             type: "array",
-            maxItems: 50,
-            items: VERIFICATION_RECEIPT_SCHEMA,
+            items: PROOF_RECEIPT_SCHEMA,
         },
         type: {
             type: "string",
@@ -574,13 +586,15 @@ const entitySchema = {
                     anyOf: [
                         { required: ["verification_scope"] },
                         { required: ["verification_perspective"] },
-                        { required: ["verification_receipts"] },
+                        { required: ["proof_contract"] },
+                        { required: ["proof_bindings"] },
+                        { required: ["proof_receipts"] },
                     ],
                 },
             },
         },
         {
-            if: { required: ["verification_receipts"] },
+            if: { required: ["proof_receipts"] },
             // biome-ignore lint/suspicious/noThenProperty: JSON Schema conditional keyword.
             then: { required: ["verification_scope"] },
         },
@@ -597,6 +611,8 @@ const entitySchema = {
                         { required: ["semantic_inventory_version"] },
                         { required: ["semantic_source_field"] },
                         { required: ["semantic_source_hash"] },
+                        { required: ["proof_exempt"] },
+                        { required: ["proof_exempt_reason"] },
                     ],
                 },
             },

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 ...`.
-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 `proofSnapshotChanges`. 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.
+- 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 ...`.
-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.

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

@@ -0,0 +1,6 @@
+# Source authoring
+
+Use `document.path`/`document.body` for source-first writes. Preserve existing
+body bytes when body is omitted, patch relationship shards without dropping
+unrelated records, and follow typed repair actions after partial completion.
+

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

@@ -0,0 +1,8 @@
+# Traceability detail
+
+Model one requirement clause at a time. Use strict fact lanes for contradiction
+checks, predicate schemas for project ontology, and observation/meta facts for
+bugs and workarounds. Query all relationship endpoints before writing; a graph
+link is not proof until the scenario, test, symbol, and fresh receipt are
+readable at the current snapshot.
+