kibi-cursor 0.6.0 → 1.0.1

package/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "kibi-cursor",
   "displayName": "Kibi",
-  "version": "0.6.0",
+  "version": "1.0.1",
   "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,186 @@
 # kibi-cursor
 
+## 1.0.1
+
+### Patch Changes
+
+- Cursor agents now get an always-on CLI recipe when Kibi MCP tools are missing, instead of treating Kibi as unavailable.
+
+  - Put the exact `npx --no-install kibi <route> --input -` command, MCP-to-CLI name mapping, and Shell-approval language in the always-applied workflow rule.
+  - Keep published plugin hooks advisory and untrusted by default; dogfood still opts into `--trusted-workspace` locally.
+  - Document the operator prerequisites (Agent mode, Shell, trusted workspace, project-local CLI) for the fallback to run.
+
+## 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

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
 
@@ -132,6 +135,21 @@ Per the thin-adapter architecture, `kibi-cursor` does not:
 - **Editor-specific value**: Cursor hooks for read/write reminders and session freshness follow-ups
 - **Foundation**: `kibi-core`, `kibi-cli`, and `kibi-mcp` remain required for project-local operations
 
+## CLI fallback when MCP is unavailable
+
+The always-on `kibi-workflow` rule selects the trusted project-local CLI when Kibi MCP tools are not in the tool list. Hooks stay advisory and never execute that CLI themselves.
+
+For the agent to actually run the fallback, the Cursor session needs:
+
+- Agent mode with Shell enabled (Ask mode cannot run the CLI)
+- A trusted workspace, or explicit operator approval of the project-local CLI
+- Project-local `kibi-cli` (use `npx --no-install kibi` or `bunx --no-install kibi`; never a global or installing runner)
+- Plugin rules loaded in the Cursor harness
+
+If MCP tools are visible, use MCP and do not use this CLI path. If Shell is unavailable or the workspace is untrusted, stop and ask the operator; do not probe the CLI.
+
+A Cursor model invoked outside Cursor's plugin harness will not load this rule. Inject the same always-on guidance into that host's system prompt or `AGENTS.md`.
+
 ## License
 
 AGPL-3.0-or-later

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.6.0",
+  "version": "1.0.1",
   "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 `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.
-- 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,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.