kibi-cursor 0.5.1 → 1.0.0

package/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "kibi-cursor",
   "displayName": "Kibi",
-  "version": "0.5.1",
+  "version": "1.0.0",
   "description": "Optional Cursor adapter for Kibi. Requires SWI-Prolog 9+ and project-local kibi-cli, kibi-mcp, and kibi-core before the bundled MCP server can start.",
   "license": "AGPL-3.0-or-later",
   "author": {

package/CHANGELOG.md

@@ -1,5 +1,212 @@
 # kibi-cursor
 
+## 1.0.0
+
+### Major Changes
+
+- 9e6fb3f: Kibi now uses one opinionated project contract: all Kibi-managed knowledge lives under `.kb/`, check enforcement is owned by the installed Kibi version, and projects can no longer weaken health by disabling rules or relocating entity paths in `.kb/config.json`. Existing repositories must run `kibi migrate --yes` to move legacy `documentation/...` knowledge into the canonical layout and adopt `.kb/manifest.json`.
+
+  Advisory modeling checks still run by default, but they report as non-blocking quality diagnostics instead of failing `kibi check`. Migration rewrites the old blanket `.kb/` gitignore stanza so authored lanes are trackable, and a malformed leftover `config.json` blocks the one-way cutover instead of guessing default paths.
+
+  - Remove user-configurable entity paths and persistent `checks.rules` overrides; retire `.kb/config.json` after migration.
+  - Introduce `.kb/manifest.json` for Kibi-owned lifecycle metadata (schema version, semantic backfill state).
+  - Add one-way legacy storage migration (`documentation/` and custom configured paths → `.kb/<lane>/`).
+  - Split check results by enforcement class: canonical → blocking violations; advisory → quality diagnostics; migration → explicit `--rules` only. Default execution is derived from the class (no separate `runsByDefault` flag).
+  - Normalize legacy Kibi `.gitignore` fences during init and migrate; treat `.kb/migrations/` as derived runtime state.
+  - Fail closed when leftover `.kb/config.json` cannot be parsed.
+  - Update init, sync, hooks, staged evidence, doctor, migration-plan, and integration packages for canonical paths.
+  - Generate the requirement-health report on pull requests as a `kibi-pr-report` artifact; keep GitHub Pages deployment on the default branch only.
+  - OpenCode treats canonical `.kb/` entity lanes as knowledge that requires evidence; only derived runtime trees (and leftover `config.json`) are ignored.
+  - Cursor and Codex hook path policy treat canonical `.kb/` lanes as tracked knowledge, not opaque compiled-store paths.
+  - Pending relationship shards are not treated as symbols manifests during source discovery.
+
+- 4c75e4d: Kibi onboarding now separates repository initialization from teaching Kibi about an existing codebase. After `kibi init`, an agent can run the `kibi-bootstrap` workflow to produce a reviewable, hash-bound plan and apply the exact approved plan safely. The old autopilot and init-kibi public names are removed so new users see one clear bootstrap path.
+
+  - Replace `kb_autopilot_generate`/`autopilot-generate` with `kb_plan_bootstrap`/`plan-bootstrap`.
+  - Add `kibi.bootstrap-plan.v1` validation, deterministic approval hashes, dependency ordering, stale-plan checks, and typed bootstrap recovery through `kb_apply_plan`.
+  - Synchronize the four canonical skill mirrors and update client adapters, docs, fixtures, and SkillOpt cases.
+
+### Patch Changes
+
+- a2acea9: Kibi now has a source-first, exact-Git runtime contract for first-party
+  adapters. CLI JSON and MCP structured results share a versioned envelope with
+  effect and repair information, while branch stores are hashed and explicitly
+  identity-bound. The mutation path can author tracked source documents and
+  canonical relationship shards without staging or committing them.
+
+  - Add the `kibi-runtime` first-party integration package.
+  - Add exact branch-store manifests, explicit legacy migration/quarantine, and
+    typed result/effect contracts.
+  - Add source-first document writes, relationship-shard updates, and deletion
+    approval plans.
+
+- 3d7d04f: Generic MCP and CLI agents now discover Kibi's operating rules from bundled skills instead of a long copy-paste prompt. Improving an existing product KB is covered by a `kibi-usage` resource rather than a second manual, so agent guidance stays in one place and cannot drift from the packaged workflow.
+
+  - Add `kibi-usage` `resources/kb-improvement.md` and bump that skill to 2.1.0.
+  - Replace `docs/prompts/llm-rules.md` with `docs/generic-agent-onboarding.md`.
+  - Remove the obsolete retroactive-init prompt; bootstrap stays in the `kibi-bootstrap` skill.
+
+- 29793c7: The Cursor stop hook no longer starts an extra Kibi follow-up after you only deliver a plan. Reads and search no longer look like source edits, so plan mode can finish without an impact-check nudge. If that same turn actually edited source or updated the knowledge base, the existing follow-up still runs.
+
+  - Record dirty paths only from known editable tools.
+  - Treat `CreatePlan` as plan delivery and stay silent at stop unless that turn also edited source or mutated the KB.
+  - Skip follow-up when `stop.status` is `aborted` or `error`.
+
+- 8db2e37: Cursor plugin users can now enable Kibi without adding a separate project MCP configuration. The plugin finds the `kibi-mcp` version installed in the opened project, starts it inside that workspace, and reports a clear setup error when the dependency is missing. It never downloads or falls back to a global Kibi runtime.
+
+  - Replace the plugin MCP `npx --no-install` command with the packaged consumer-workspace launcher.
+  - Cover isolated and packed plugin launches, workspace selection, package-layout resolution, exit codes, and signal forwarding.
+
+- 535dea8: Agents can now keep working in synthetic, detached, or unreadable workspaces while Kibi reports the migration work it can evaluate. Coverage and checks preserve their useful domain results when branch status is unavailable, and the Codex/Cursor skill assets now stay aligned with their published plugin metadata.
+
+  - Keep status-derived migration actions read-only and append them only when branch resolution succeeds.
+  - Preserve the shared migration-plan contract across coverage and checks without requiring a Prolog-backed status query in non-Git harnesses.
+  - Synchronize plugin manifests and freshness skill CLI examples for the next coordinated patch release.
+
+- b746960: Kibi now teaches and enforces requirement supersession in one consistent
+  direction: the replacement points to the requirement it replaces. Reversed
+  edges can no longer hide a newer contradictory policy merely by making that
+  newer requirement non-current. Relationship checks also block authored links
+  that have silently disappeared from compiled knowledge.
+
+  - Document `supersedes` as new-to-old across bundled and generated skills.
+  - Reject reversed supersession when tracked source history proves that the
+    purported replacement predates its target.
+  - Restrict legacy branch migration to literal-to-hashed storage conversion for
+    the same exact Git identity; every cross-identity pair is refused.
+  - Cover exact-Git branch policy conflicts and approved evolution with Prolog
+    regression tests.
+  - Preserve partial-upsert relationship projections and validate
+    authored-to-compiled relationship parity.
+
+- Updated dependencies [6ca08bb]
+- Updated dependencies [a2acea9]
+- Updated dependencies [33262f8]
+- Updated dependencies [9e6fb3f]
+- Updated dependencies [3d7d04f]
+- Updated dependencies [2d6cc59]
+- Updated dependencies [8f71f1a]
+- Updated dependencies [a07fad5]
+- Updated dependencies [2e68da9]
+- Updated dependencies [4cf383b]
+- Updated dependencies [7bc4f61]
+- Updated dependencies [15b5825]
+- Updated dependencies [51fb55b]
+- Updated dependencies [1ca62af]
+- Updated dependencies [f1a6d5c]
+- Updated dependencies [1ca62af]
+- Updated dependencies [44fd818]
+- Updated dependencies [8fe890c]
+- Updated dependencies
+- Updated dependencies [7654339]
+- Updated dependencies [c77d3f1]
+- Updated dependencies [967cef7]
+- Updated dependencies [395e38f]
+- Updated dependencies
+- Updated dependencies [535dea8]
+- Updated dependencies [5fdb828]
+- Updated dependencies [b97329a]
+- Updated dependencies [4c75e4d]
+- Updated dependencies [c942344]
+- Updated dependencies [07803e4]
+- Updated dependencies [b746960]
+- Updated dependencies [400e88c]
+  - kibi-cli@1.0.0
+  - kibi-mcp@1.0.0
+
+## Unreleased
+
+### Patch Changes
+
+- The published Cursor plugin now launches the `kibi-mcp` installed in the opened project, even when Cursor starts plugin processes from the plugin installation directory. The launcher preserves the consumer workspace as the child cwd and `KIBI_WORKSPACE`, and fails with an actionable message when the project-local package is missing.
+
+  - Replace plugin MCP's ambient `npx --no-install` invocation with the packaged consumer-local resolver.
+  - Add isolated and packed-artifact coverage for workspace resolution, package layouts, exit codes, signals, and missing-runtime failures.
+
+## 0.6.3
+
+### Patch Changes
+
+- Existing Kibi installations now receive an agent-guided migration workflow instead of opaque repair advice. Status, checks, and coverage expose one deterministic, hash-bound action plan; agents can safely apply only explicitly approved automatic repairs while semantic, proof, package, and operator work remains visible for review. This makes damaged or legacy KBs recoverable without direct `.kb` edits and gives every run an auditable post-application readback.
+
+  - Add `kibi.migration-plan.v2` fragments to the 21-operation surfaces and support hash/action authorization in `kb_apply_plan` and `kibi migrate --apply-safe`.
+  - Add lazy status/planning and deterministic schema, branch, storage, coordinate, and recovery action execution with workspace-root-safe CLI/MCP parity.
+  - Refresh agent skills, traceability fixtures, and SkillOpt coverage for migration safety boundaries and five-axis closeout reporting.
+
+## 0.6.2
+
+### Patch Changes
+
+- de7b85a: Verification contracts can now evolve without forcing projects to erase valid historical test evidence. Kibi preserves every earlier receipt, accepts a newly appended receipt for the current contract, and only treats evidence matching both the current contract and live code snapshot as proof.
+
+  - Separate immutable receipt-history validation from current-contract binding during verification ingest.
+  - Report `verification_contract_mismatch` as an explicit proof gap until current-contract evidence is appended.
+  - Teach the usage skill and SkillOpt evaluator to preserve older-contract receipts and forbid history rewrites.
+
+- 584336b: Agents now get consistent guidance when execution proof, structural coverage, and KB freshness disagree. Current-contract E2E evidence is recorded as v2 without rewriting history, and full checks no longer report a contradictory weak-depth warning when the same live receipt already proves the scenario-backed test. Receipt freshness repairs also identify the affected requirements and tests so agents can rerun the exact contract.
+
+  - Share snapshot-bound proof evidence with full quality diagnostics.
+  - Add bounded receipt-gap telemetry and v2-native remediation guidance.
+  - Document and test the new receipt and proof-aware diagnostic requirements.
+  - Refresh the mirrored usage skills and dogfood-derived SkillOpt expectations.
+  - Keep the MCP package contract verifier self-contained with an explicit semver development dependency and matching workspace lock ranges.
+
+- Kibi can now explain a missing or damaged branch-local KB without changing it. Agents receive a precise recovery path, preserving the existing store before a deliberate rebuild, and no longer need to guess whether a clean check also means a clean, fresh KB.
+
+  - Add non-mutating branch-store inspection to status and a preview-first `kibi branch recover --apply` workflow.
+  - Restrict branch migration to the detected historical `master` -> legacy `main` compatibility attachment; arbitrary branch moves are refused.
+  - Refresh CLI/MCP status documentation, mirrored agent skills, and release-gate packed consumer coverage.
+
+- ef75929: Kibi’s release checks now validate compiled package APIs and dependency ranges in isolated npm and pnpm consumers, while the usage skill and private SkillOpt evaluator report task completion, KB freshness, verification, proof, and accepted limitations independently. Consumer repositories keep ownership of their local artifact update scripts and dependency overrides.
+
+  - Remove library-side consumer dogfood installers and retain release-only packed checks.
+  - Add deterministic closeout expectations and dogfood-derived held-out cases.
+
+## 0.6.1
+
+### Patch Changes
+
+- Dogfood projects now get branch-local knowledge bases that follow the exact Git ref, actionable stale-source diagnostics, and a sanctioned relationship cleanup path. Verification receipts and packed package provenance are stricter and reproducible, while agents receive conservative symbol-recovery guidance and explicit interim-state signals. This prevents silent `master`/`main` drift and makes passing E2E evidence distinguishable from complete semantic proof.
+
+  - Remove implicit branch-name normalization and add previewed legacy branch migration.
+  - Add exact relationship deletion, v2 receipt/schema parity, status diagnostics, dogfood package manifests, and SkillOpt cases.
+
+## 0.6.0
+
+### Minor Changes
+
+- Coverage reports now distinguish structural linkage from a conservative end-to-end requirement proof. Users can see exactly which semantic, contradiction, scenario, E2E, symbol, or source-coordinate stage prevents proof, together with ranked repair guidance; executable test symbols also stop inflating production-coverage counts. Structured proposition ledgers and refreshed symbol coordinates now survive sync as queryable proof evidence.
+
+  Current requirement ingestion now fails closed when assertive prose is missing from its ledger, drifts from its source hash or byte spans, duplicates an identity, or claims a modeled representation without exactly one same-key grounding fact. Markdown projects receive a compatibility baseline before new or semantically edited requirements are held to the contract, and explicit unresolved states remain usable without being misreported as consistency.
+
+  Proof-bearing tests now keep append-only execution receipts tied to the current deterministic workspace snapshot. Coverage and status expose that snapshot through CLI and MCP, and missing, stale, failed, malformed, mismatched, future-dated, or unavailable evidence can no longer inherit authority from a durable `passing` label.
+
+  Requirement coverage now turns proof gaps into a deterministic read-only migration plan. Users can work one validated dependency batch at a time, see when pagination makes a plan incomplete, and avoid applying downstream links or receipts before their semantic and graph prerequisites exist.
+
+  Diagnostic usage evidence now drives a versioned workflow acceptance report. Users can enforce fresh advisor, validation, source-lookup, proof-recovery, receipt, and mutation-retry evidence from the CLI, while unfiltered CLI/MCP checks surface ranked project-local repairs without treating missing or stale telemetry as a pass.
+
+  Distribution audits now compare the same six requirement-compiler behaviors across source, freshly packed CLI/MCP packages, and the binaries actually resolved by dogfood or pinned projects. Unsupported legacy capabilities remain explicit non-matches, executable provenance is inspected directly, and every project divergence needs a named upgrade or compatibility action.
+
+  Diagnostic workflows now produce correlated evidence through both CLI JSON and MCP surfaces. Operators can run a read-only versioned remediation report that points to exact unmatched log events, preserves explicit missing-coverage work, and prevents advisor or preflight evidence from a different identified session or actor from counting as proof.
+
+  Legacy prose can now be inspected one requirement at a time through a deterministic migration preview. The preview preserves existing code evidence, binds every extracted proposition to exact authored source, ranks project-local ontology candidates, and never emits an auto-applicable write.
+
+  - Add the shared `kibi.requirement-proof.v2` Prolog evaluator and expose its rows, fresh receipt evidence, and summary counts through CLI and MCP coverage.
+  - Persist generated symbol coordinates and symbol metadata into normal and staged RDF projections.
+  - Preserve semantic-inventory JSON through mutation, sync, RDF storage, and query round trips, and refresh coordinates before extracting their manifest overlay.
+  - Render proof state and proof gaps in the CLI coverage table, and classify symbol traceability roles explicitly.
+  - Document the proof contract and update the bundled traceability skill to use proof outcomes instead of structural counts as its success boundary.
+  - Add the versioned `kibi.semantic-inventory.v1` boundary to CLI/MCP preflight, upsert, modeling plans, and Markdown sync, with packed-package E2E coverage.
+  - Preserve JSON Schema `const` values through MCP's Zod adapter so source and packed tool contracts enforce and advertise the same inventory version.
+  - Add append-only `kibi.verification-receipt.v1` validation, RDF/Markdown persistence, snapshot-bound freshness checks, explicit repair gaps, and CLI/MCP workspace-snapshot parity.
+  - Discover project-local predicate schemas from normalized RDF, withhold write plans for unbound ordered arguments, and accept exact `schemaId`, `argumentBindings`, and reviewed `polarityHint` inputs for conservative completion without lexical guessing.
+  - Attach source-bound strict, predicate, and rule witnesses to contradiction diagnostics, preserving unresolved rule overlap as incomplete analysis in requirement proof.
+  - Add `kibi.repair-plan.v1` to requirement coverage with stable plan IDs, per-requirement dependency batches, pagination fail-closed behavior, validation workflows, and non-auto-applicable sequential mutation policy across CLI and MCP.
+  - Add `kibi.telemetry-acceptance.v1`, exact mutation fingerprints, coverage recovery/receipt event fields, the `usage-metrics --require-acceptance` gate, and telemetry-backed full-check quality diagnostics.
+  - Add `kibi.distribution-parity.v1`, executable-derived runtime provenance, stable semantic normalization, action-bound project divergences, and packed/project-resolved E2E fixtures for the six requirement-compiler capabilities.
+  - Add CLI JSON diagnostic logging, opaque session/actor correlation, and the deterministic read-only `kibi.telemetry-remediation.v1` report and command.
+  - Add `kibi.legacy-migration-plan.v1` to CLI and MCP coverage with fail-closed source binding, exact proposition inventories, schema-provenance ranking, deterministic pagination, and packed read-only E2E coverage. Requirement-only `semantic_text` now carries authored prose independently from `text_ref` evidence, and semantic source drift blocks review application.
+
 ## 0.5.1
 
 ### Patch Changes

package/README.md

@@ -12,7 +12,7 @@ Install these **before** enabling the plugin MCP server:
 | --- | --- |
 | **SWI-Prolog 9+** (`swipl` on `PATH`) | Powers Kibi inference and validation |
 | **`kibi-cli`** | Project CLI (`kibi` command) |
-| **`kibi-mcp`** | MCP server the plugin's `mcp.json` invokes via `npx --no-install kibi-mcp` |
+| **`kibi-mcp`** | MCP server installed in the opened project; the plugin launcher resolves this package without downloading it |
 | **`kibi-core`** | Shared graph/runtime dependency |
 
 ```bash
@@ -25,7 +25,7 @@ Full setup: [docs/install.md](https://github.com/Looted/kibi/blob/develop/docs/i
 
 Add this plugin only after the base packages work in your project.
 
-**Git worktrees:** the published plugin MCP entry (`npx --no-install kibi-mcp`) needs `kibi-mcp` resolvable from that worktree's `node_modules` (run install there). For this monorepo's dogfood path, prefer project `.cursor/mcp.json`, which can fall back to the primary checkout's built MCP — see [DEV.md](./DEV.md#linked-worktrees).
+**Git worktrees:** the published plugin MCP entry resolves `kibi-mcp` from the opened worktree's `node_modules` (run install there). The plugin does not download or bundle a Kibi runtime. For this monorepo's dogfood path, prefer project `.cursor/mcp.json`, which can fall back to the primary checkout's built MCP — see [DEV.md](./DEV.md#linked-worktrees).
 
 ## Installation
 
@@ -55,14 +55,17 @@ cp -r "$(npm root)/kibi-cursor" ~/.cursor/plugins/local/kibi-cursor
 
 ## MCP configuration
 
-The plugin bundles `mcp.json` pointing at the project-local `kibi-mcp` binary:
+The plugin bundles `mcp.json` with a thin launcher that locates and starts the
+`kibi-mcp` package installed in the opened project. The launcher runs from the
+consumer workspace and sets `KIBI_WORKSPACE` to that root; it never downloads,
+bundles, or falls back to a global Kibi runtime:
 
 ```json
 {
   "mcpServers": {
     "kibi": {
-      "command": "npx",
-      "args": ["--no-install", "kibi-mcp"]
+      "command": "node",
+      "args": ["bin/launch-kibi-mcp.mjs", "${workspaceFolder}"]
     }
   }
 }
@@ -90,7 +93,7 @@ Manual MCP fallback (no plugin install required):
 ```
 agent-plugin/
 ├── plugin.json   # agent-plugins.org/schemas/1.0.0/plugin.schema.json
-├── skills/       # canonical Kibi Agent Skills (kibi-usage, init-kibi, ...)
+├── skills/       # canonical Kibi Agent Skills (kibi-usage, kibi-bootstrap, ...)
 └── mcp.json      # agent-plugins.org/schemas/1.0.0/mcp.schema.json (stdio kibi-mcp)
 ```
 
@@ -103,18 +106,18 @@ agent-plugin/
 ### Discovery-first rules and skills
 
 - **Rules**: always-on capability-based workflow guidance plus optional traceability rules for source files.
-- **Skills**: `kibi-usage`, `init-kibi`, `kibi-freshness`, and `kibi-traceability`.
-- **Commands**: `/init-kibi` documents the `kb_autopilot_generate` bootstrap workflow.
+- **Skills**: `kibi-usage`, `kibi-bootstrap`, `kibi-freshness`, and `kibi-traceability`.
+- **Commands**: `/kibi-bootstrap` documents the `kb_plan_bootstrap` bootstrap workflow.
 
 ### Advisory editor hooks
 
 Hooks are warning-only and never replace MCP/CLI behavior:
 
-- **sessionStart**: bootstrap reminder when `.kb/config.json` is missing.
+- **sessionStart**: bootstrap reminder when `.kb/manifest.json` is missing.
 - **preToolUse**: warns on explicit direct `.kb/**` edits without blocking.
 - **beforeReadFile** and **postToolUse (Read)**: inject source-linked lookup guidance once per path per session.
 - **postToolUse (Write/Edit)**: inject traceability and freshness guidance once per path per session, including `kb_check({sourceFiles:[...], includeImpactDiagnostics:true, includeWorkingTreeDiff:true})` for meaningful source edits.
-- **stop**: emits a single freshness or impact-check follow-up when meaningful paths changed during the session.
+- **stop**: emits a single freshness or impact-check follow-up when meaningful paths were **edited** during the turn (reads and search do not count). Plan delivery (`CreatePlan`) stays silent unless that same turn also edited source or mutated the KB.
 
 ### What the plugin does not do
 

package/agent-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "kibi",
-  "version": "0.5.1",
+  "version": "1.0.0",
   "description": "Repo-local, per-branch, queryable knowledge base. Portable Agent Plugin packaging Kibi's Agent Skills and MCP server.",
   "author": { "name": "Kibi" },
   "homepage": "https://github.com/Looted/kibi/blob/develop/docs/install.md",

package/agent-plugin/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/agent-plugin/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/agent-plugin/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/agent-plugin/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/agent-plugin/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/agent-plugin/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/agent-plugin/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/agent-plugin/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/agent-plugin/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/agent-plugin/skills/kibi-traceability/SKILL.md

@@ -1,54 +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 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 -`.
 
-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:
+## Workflow
 
-```bash
-echo '{"sourceFiles":["src/auth/login.ts"],"includeImpactDiagnostics":true,"includeWorkingTreeDiff":true}' | npx --no-install kibi check --input -
-```
+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`.
 
-## Capability Workflow
+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.
 
-- 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.
-- Use `kb_delete` or `delete --input` only for explicit cleanup of obsolete records or relationships.
+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.
 
-## Guidance
+## Typed recovery and proof
 
-- 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.
-- 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.
+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.
 
-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}
+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/agent-plugin/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.
+