kibi-cli 0.19.0 → 2.0.0

package/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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.
+