CLI reference

This document provides complete command-by-command documentation for the kibi CLI. The CLI is both a human-facing command surface and an agent-accessible peer of MCP.

Dedicated JSON operation routes

The CLI exposes the canonical public operation catalog as a peer to MCP. Every route accepts one JSON object through --input <file|->, where a path is resolved from the current working directory and - reads standard input exactly once. JSON mode writes one structured JSON value followed by a newline to stdout.

# Read an input object from a file
kibi query --input request.json

# Read the same object from stdin
printf '%s\n' '{"query":"login","limit":10}' | kibi search --input -

The input root must be a JSON object that matches the corresponding operation schema. In JSON mode, do not also pass business flags or positional arguments; mixed input is rejected. Optional _diagnostic_telemetry is transport metadata and is removed before business-schema validation. Add the global --diagnostic-mode flag to append the operation outcome to .kb/usage.log; supplied opaque session_id and actor_id fields are preserved for workflow correlation.

JSON-route exit codes

Errors are written to stderr as Error [CODE]: detail. Failed routes do not write a success JSON object.

kibi init

Initializes Kibi repository infrastructure in the current directory. It does not infer or write product knowledge.

Behavior:

• Creates .kb/ directory structure with canonical knowledge lanes (requirements/, scenarios/, tests/, facts/, adr/, flags/, events/)
• Installs git hooks (pre-commit, post-checkout, post-merge, post-rewrite) by default, into the directory Git reads hooks from (git rev-parse --git-path hooks), so linked worktrees and core.hooksPath are honored. Re-running kibi init refreshes only the kibi-managed section of each hook. Hooks resolve the kibi binary at run time (PATH first, then node_modules/.bin walking up from the repository root), so they work with both global and project-local installs even though git does not put node_modules/.bin on the hook's PATH.
• Ignores derived .kb/ runtime state in .gitignore (.kb/branches/, .kb/recovery/, .kb/proof/runs/, .kb/briefs/, .kb/migrations/, .kb/usage.log). Authored knowledge under .kb/ stays tracked. kibi migrate also removes the pre-canonical blanket .kb/ ignore stanza so migrated knowledge files are not left Git-ignored.
• Creates Kibi-owned .kb/manifest.json (lifecycle metadata only; not a user configuration file)
• Creates .kb/symbols.yaml and .kb/symbol-coordinates.yaml when they do not already exist

Flags:

• --no-hooks - Skip git hook installation (hooks are installed by default)
• --github - Scaffold the documented GitHub Pages badge + full report integration (workflow, README badge, kibi-report/ gitignore entry)
• --badge-only - With --github only: publish the badge without the HTML report. Rejected if used alone.

GitHub integration:

• --github by itself always means badge + full report. It copies the canonical workflow from the kibi-cli package (the same file as docs/examples/github/kibi-report.yml). That workflow generates the report on pull requests (artifact only) and deploys GitHub Pages only from the repository default branch or workflow_dispatch.
• Re-running is safe: matching files are left as already configured; customized workflows are not overwritten; an existing Kibi badge is not duplicated.
• If no README exists, the workflow is still written and the badge Markdown is printed.
• If a github.com owner/repository cannot be determined from git remotes, the workflow is still written and placeholder badge Markdown is printed instead of inventing a URL.
• After scaffolding, enable Settings → Pages → Source → GitHub Actions. See GitHub badge + report.

Notes:

• Hooks are installed by default. Only use --no-hooks if you specifically don't want automated syncing.
• The pre-commit hook blocks commits when .kb/symbol-coordinates.yaml has unstaged changes, forcing refreshed symbol coordinates to be staged with the related code changes.
• The pre-commit hook also blocks behavior-changing source edits that lack staged Kibi impact evidence (KB entity docs or refreshed manifest). Test-only and docs-only edits are exempt.
• Idempotent: safe to run multiple times
• After initialization, ask the coding agent to bootstrap the repository. The bootstrap planner owns discovery, approval, source-first application, and repair; doctor and sync are diagnostics/internal lifecycle operations.
• After running, see the quick start guide in README.md for next steps

kibi sync

Extracts entities and relationships from project documents and updates the knowledge base.

Behavior:

• Extracts entities from Markdown files with frontmatter
• Imports symbols from YAML manifests
• Updates KB for the current git branch
• Runs validation rules on the updated KB

Flags:

• --validate-only - Perform validation without making mutations
• --rebuild - Rebuild branch snapshot from scratch (discards current KB)
• --refresh-symbol-coordinates - Refresh symbol location data in .kb/symbol-coordinates.yaml during sync. Explicit refreshes are fatal on artifact errors, force coordinate-bearing symbols to persist even when normalized hashes match cached state, and only then advance the sync cache (version 2, workspace-root-relative keys; the artifact is a compiler dependency of symbols.yaml). Extraction misses are reported as failed, including Python and other files handled by the text heuristic. If a qualified symbol title cannot be located, query and validate/upsert a corrected title/sourceFile or an intentional granularity_reason: extractor-miss before refreshing. Coverage only offers automatic coordinate repair when current extraction or an explicit coarse anchor can produce coordinates.

Notes (sync + MCP):

• Rebuild with --rebuild replaces the on-disk branch KB snapshot while MCP can continue running.
• A running MCP session detects same-branch snapshot replacement before serving affected operations.
• If auto-refresh cannot complete during a transient publish conflict, MCP returns a recovery error; retry the tool call after the publish settles.

Notes:

• Supports these entity types: req, scenario, test, adr, flag, event, symbol, fact
• Modeling: Use flag for runtime/config gates; record bugs and workarounds as fact entities, usually with fact_kind: observation or meta. Strict facts (subject, property_value) drive contradiction checks, while observation/meta facts are non-blocking notes.
• Symbol manifests must be in YAML format
• Changes are committed to the branch KB's audit log

Normal sync is a delta compile into the running Node engine: unchanged source files are skipped, changed/deleted source entities are retracted and reasserted in the journal, and relationship shards are refreshed only when their content hash changes. --rebuild is the explicit generation-replacement path.

kibi engine status|stop|janitor

The engine is automatically started for CLI and MCP operations. engine status prints the workspace/branch daemon PID and journal status; engine stop asks it to flush and exit. A daemon is shared by all clients for the same canonical workspace path and branch and exits after ten minutes without clients.

engine janitor classifies stale engine daemons and branch-store locks left by crashed engines or removed worktrees. It only reports by default; --apply performs the cleanup, --all also sweeps daemon sockets from other workspaces, and --format json|table selects the output.

kibi storage status|compact|export

• storage status reports journaled mode, generation, commit sequence, and journal bytes.
• storage compact explicitly compacts the RDF journal; idle engines also compact journals over 16 MiB.
• storage export --output <directory> writes derived legacy kb.rdf and audit.log files outside the active branch store. These exports are not authoritative and are never read by the engine.

Node.js 22 or newer is required for both the CLI/MCP clients and the engine. Bun remains a repository build/test tool, but is not a supported runtime for the published Kibi packages.

kibi prove

Runs the configured proof producers and ingests valid kibi.proof-run.v1 evidence. For each integration, the producer executes once (shell: false), the workspace snapshot is revalidated before and after, and the artifact is evaluated independently against every selected test's kibi.proof-contract.v1 obligations. Derived kibi.proof-receipt.v1 receipts append idempotently; history is never rewritten.

kibi prove --all
kibi prove --test TEST-checkout
kibi prove --requirement REQ-checkout
kibi prove --integration web-e2e
kibi prove --integration web-e2e,api-tests
kibi prove --all --integration-except heavy-suite

Selectors: --test, --requirement, --integration, --all (default). --integration accepts one or more comma-separated integration ids. --integration-except is a modifier (it requires a selector such as --all) that skips tests bound to the listed integrations. A selector that matches no proof-bearing test is an error, so a typo cannot silently prove nothing. The exit code is non-zero when any proof fails or a producer errors.

Producer child processes run with KIBI_PROOF_RUN=1 (plus KIBI_PROOF_OUTPUT, KIBI_PROOF_SNAPSHOT, and other KIBI_PROOF_* variables). Runner configurations that need proof-run-aware behavior — disabling retries, for example — should branch on KIBI_PROOF_RUN instead of inferring a proof run from output-path variables.

kibi proof inspect

Detects languages, build systems, test frameworks, CI workflows, configured integrations, and the recommended integration level. Deterministic output for agents; bootstrap consumes this instead of reinventing detection.

kibi proof inspect --json

kibi proof explain

Projects one requirement (REQ-*) or symbol (SYM-*) from the same kibi.requirement-proof.v3 Proof that coverage uses. Human output labels required_proofs, executable_for, and covered_by as separate blocks so agents cannot treat them as one chain. --json emits the structured projection (primary plus optional secondary covered_by reasons). This command does not re-evaluate qualification.

kibi proof explain REQ-EXAMPLE
kibi proof explain SYM-EXAMPLE
kibi proof explain --requirement REQ-EXAMPLE --json
kibi proof explain --symbol SYM-EXAMPLE --json

kibi proof impact

Compares the current Proof projection to HEAD:proof/baseline.json, the committed ratchet snapshot — not the working-tree copy. This is a diagnostic command: it reports fingerprint differences and exits 0 when evaluation succeeds. The strict ratchet remains scripts/check-proof-baseline.mjs. Human output names the committed file as the comparison target and prints requirement-level fingerprint diffs plus live coverage explanations.

kibi proof impact
kibi proof impact --json

See proving requirements for the full workflow: proof contracts, integration configuration, the artifact reference, adapter authoring, and troubleshooting. Playwright is an optional first-party producer (kibi-cli/playwright-reporter); Kibi itself is runner-neutral. See the proof ladder for what each proof stage and status means.

kibi proof prune

Shrinks each test's proof_receipts history to its newest entries. Re-proving the same snapshot appends a receipt per run, so duplicate passed blocks accumulate; prune keeps the newest --keep <n> (default 1) per test and reports the before/after counts. This is the one sanctioned history-shrinking mutation — pruned histories remain ordered, structurally valid evidence, and current-binding rules still apply to the newest receipt.

kibi proof prune              # keep the newest receipt per test
kibi proof prune --keep 3     # keep the newest three
kibi proof prune --test TEST-E2E-EDITOR-001

kibi proof migrate-legacy

Removes legacy verification_receipts frontmatter blocks from test documents that already carry a proof_contract. The old blocks contain stale snapshot hashes and make live-receipt greps error-prone. The block is spliced out of the authored document and the compiled property is dropped — nothing else in the document is rewritten.

kibi proof migrate-legacy
kibi proof migrate-legacy --test TEST-LEGACY-001

kibi query [type]

Queries entities from the knowledge base.

Syntax:

kibi query [type] [--id ID] [--tag TAG] [--source PATH] [--relationships ID] [--format json|table] [--limit N] [--offset N]

Arguments:

• [type] - Optional entity type to query (req, scenario, test, adr, flag, event, symbol, fact)
• --id ID - Query by exact entity ID
• --tag TAG - Filter by tag
• --source PATH - Filter by source file path substring
• --relationships ID - Return relationships for a specific entity ID
• --format json|table - Output format (default: json)
• --limit N - Maximum number of results to return (default: 100)
• --offset N - Number of results to skip (pagination)

Examples:

# List all requirements as table
kibi query req --format table

# Find specific test
kibi query test --id TEST-mcp-search-discovery

# Find all entities with "security" tag
kibi query req --tag security --format table

# Find entities linked to a source file path
kibi query symbol --source src/auth/login.ts --format table

# Show relationships for one entity
kibi query --relationships REQ-cli-gc

# Get paginated results
kibi query scenario --limit 10 --offset 0
kibi query scenario --limit 10 --offset 10

Notes:

• Returns "No entities found" if query produces no results
• Results are deterministically ordered
• Type, ID, and tag filters can be combined

kibi search <query>

Searches entity metadata and markdown body text for exploratory discovery. The JSON route also supports deterministic intent-v1 ranking for host-agent facets and changed source locations.

Syntax:

kibi search <query> [--type TYPE] [--format json|table] [--limit N] [--offset N]

Notes:

• Searches markdown-backed knowledge and metadata
• Does not search raw code file bodies
• Use kibi query for exact follow-up lookups

Intent mode is available through kibi search --input -:

printf '%s\n' '{
  "query": "download a report",
  "rankingMode": "intent-v1",
  "semanticFacets": {"actions": ["export"], "objects": ["CSV file"]},
  "sourceLocations": [{"path": "src/reports/export.ts", "line": 42}]
}' | kibi search --input -

Intent results include queryAnalysis, matched semantic facets, source-location evidence, bounded traceability graph paths, and abstained: true when no result reaches minScore (default 0.18). Source paths must be workspace-relative. The host agent supplies facets; Kibi does not call a model.

kibi status

Reports the current KB snapshot, branch, and freshness state.

Syntax:

kibi status [--format json|table]

JSON output also exposes proofSnapshot, availability, dirty state, file count, and kibi.workspace-snapshot.v2 version. This deterministic snapshot is the identity coverage uses to accept or reject proof receipts; an unavailable snapshot fails proof closed. Receipt-only frontmatter changes are excluded from the hash so ingesting a receipt cannot invalidate its own proof.

Status also reports the exact branchAttachment (gitBranch, kbBranch, kind, and migrationRequired), bounded staleReasons, and proofSnapshotChanges. A legacy attachment is read-compatible only; writes and sync are blocked until the sanctioned migration is applied. Dirty editor/config paths are reported rather than silently ignored.

Sync stamps the compiler contract it used (a hash of the entity property schema) into the branch store. When the store was compiled by a CLI build with a different contract, for example an older build that dropped properties it did not know, status reports syncState: "stale" with a compiler_changed reason even though every source hash still matches. The next kibi sync re-imports every source once and clears it.

Status does not initialise a missing branch store or repair a damaged one. It instead returns branchStore (missing, incomplete, or unreadable) with a recovery-oriented stale reason. Use the explicit branch commands below after reviewing that diagnosis.

When migration is needed, JSON status also returns schemaStatus and a kibi.migration-plan.v2 migrationPlan. Actions are typed with a canonical planHash, dependencies, safety class, preconditions, postconditions, and exact operation/CLI guidance. Status remains read-only.

kibi find-gaps [type] (gaps alias)

Runs curated missing/present relationship analysis.

Syntax:

kibi find-gaps [type] [--missing-rel RELS] [--present-rel RELS] [--tag TAGS] [--source PATH] [--limit N] [--offset N] [--format json|table]

Examples:

# Requirements missing scenarios or tests
kibi find-gaps req --missing-rel specified_by,verified_by --format table

# Source-linked gap analysis
kibi gaps req --source src/auth --missing-rel verified_by --format table

find-gaps is the canonical command name and dedicated JSON route. gaps is a true Commander alias for the same action, so flag and --input behavior are identical under either spelling.

kibi coverage

Generates curated coverage reports.

Syntax:

kibi coverage [--by req|symbol|type] [--tag TAGS] [--include-passing] [--status STATUSES] [--no-include-transitive] [--limit N] [--offset N] [--include-migration-preview] [--migration-limit N] [--migration-offset N] [--migration-predicate-limit N] [--migration-predicate-min-score 0..1] [--format json|table]

Notes:

• Requirement coverage summaries distinguish evaluated must-priority requirements from not_applicable rows.
• --include-passing adds rows with a proven or not-applicable proof outcome back into requirement results; compatibility-oriented structural coverage remains visible on every returned row.
• --status <statuses> (comma-separated: proven, missing, unresolved, not_applicable) selects requirement rows by proofStatus and implies include-passing. Use it to enumerate one slice — e.g. kibi coverage --by req --status not_applicable lists every out-of-scope requirement with its typed applicability reason (proofStages.applicability.reason: superseded, a status-vocabulary mismatch, or a proof exemption). The summary always reflects the whole KB; pagination applies to the filtered rows.
• Requirement coverage rows include coverage-depth labels when evidence can be classified: direct_passing_e2e, scenario_passing_e2e, unit_only, open_or_nonpassing_tests_only, scenario_only_no_test, or no_test_evidence.
• Coverage-depth labels are informational. They do not change existing covered/uncovered pass-fail semantics, and typed test fields (verification_scope, then verification_perspective) take precedence over legacy e2e tags or /e2e/ path heuristics.
• Requirement rows also expose the additive kibi.requirement-proof.v3 contract. proofStatus is proven, unresolved, missing, or not_applicable for a non-current requirement, and is intentionally independent from compatibility-oriented coverageStatus. See docs/proof-ladder.md for the per-stage semantics.
• proofStages records semantic inventory, logical grounding, contradiction, scenario, scenario-test, passing E2E, executable-symbol, production-symbol, and exact source-coordinate evidence. proofGaps lists only blocking issues that prevent proven. The passing-E2E stage exposes per-scenario scenarioObligations; every linked E2E proof-bearing test is mandatory, while unit/integration-only ancillary tests remain nonblocking when the scenario has qualifying E2E evidence. proofAdvisories is reserved for explicitly non-blocking context; missing, stale, failed, invalid, snapshot-unavailable, and contract-mismatched E2E evidence remains in proofGaps. proofRepairs ranks concrete recovery actions for blocking gaps only.
• Requirement reports also include repairPlan (kibi.repair-plan.v1). It groups gaps into one small batch per requirement and dependency phase, marks only the earliest unresolved batch ready, and links later batches through dependsOn. Every batch is read-only guidance with autoApplicable: false, a reviewed workflowSteps sequence, targeted validationRules, and a sequential-write policy.
• Requirement and symbol reports also include the shared migrationPlan (kibi.migration-plan.v2). Apply only ready automatic actions after explicitly approving its exact hash and action IDs; review, operator, and E2E execution actions remain agent/operator work.
• repairPlan.scope.complete is false and status is partial whenever limit/offset exclude actionable requirements. Increase the limit and reset the offset before using a plan as a project-wide migration inventory. The plan ID is stable for the same snapshot, filters, evidence, and gaps; receipt ages and check timestamps do not churn it.
• --include-migration-preview adds kibi.legacy-migration-plan.v1 for ready semantic-inventory batches. It defaults to one requirement, reconstructs normalized authored Markdown with exact SHA-256 source identity and UTF-8 proposition spans, ranks project-local schemas before built-ins, and emits review-only property patches. The patch stores authored prose in requirement-only semantic_text and never replaces an independent text_ref; only an existing semantic_text that differs from the current normalized Markdown blocks the batch as source drift. All candidates remain writeEligible: false and all batches autoApplicable: false.
• The passing-E2E stage requires append-only proof-receipt history for every linked scenario-backed E2E test. New evidence is produced by kibi prove as kibi.proof-receipt.v1. Only a fresh passed receipt bound to the live proofSnapshot, current contract hash, and effective execution fingerprint qualifies; authored status: passing remains structural metadata.
• Symbol rows classify traceabilityRole as production, executable_test, or mixed. Executable-only test symbols are not_applicable to production coverage instead of being counted as fully covered.

kibi report

Generates a polished, self-contained HTML view of requirement health and a matching SVG badge. This is a human-facing presentation command over the existing kb_coverage operation, not an additional JSON/MCP operation.

Syntax:

kibi report [--output PATH] [--open] [--tag TAGS] [--limit N]

Options:

• --output <path> writes to an HTML file or to index.html inside a directory. Directory output also writes badge.svg; explicit file output writes <name>.badge.svg beside the HTML. The default is kibi-report/index.html plus kibi-report/badge.svg.
• --open opens the report with the operating system's default browser after the file is written successfully.
• --tag <tags> limits requirement and symbol health to comma-separated tags.
• --limit <n> sets the maximum complete requirement row set. It defaults to 10,000 and fails instead of publishing partial per-requirement metrics.

Report contents:

• Proven percentage and count use current requirements only; superseded and otherwise non-current requirements are reported as excluded rather than lowering the score.
• Summary metrics show current requirements, strict proof coverage, missing scenarios, stale E2E evidence, unique contradiction witnesses, unmapped production symbols, and requirements without implementation.
• Requirement cards separate semantic grounding, scenario, implementation, E2E-test, and fresh-receipt stages. Search, health filters, and proof-gate filters run entirely in the generated file. Filter buttons include counts. Relative evidence and generation ages are computed in the viewer from preserved absolute timestamps.
• Stale KB state and dirty workspace proof evaluation are shown as a prominent snapshot warning.
• Stale KB state and dirty workspace proof evaluation are shown as a prominent snapshot warning.
• All KB-provided values are HTML-escaped. The report has no CDN, font, script, or other network dependency, so the output directory can be hosted as-is.
• The generated SVG badge uses the same complete coverage snapshot as the report. It pairs the Kibi logo with a kibi label in Codecov/Shields chrome (regular 11px type, #555 label pane, reserved padding, and white status text), sizes itself to the proven-percentage message, and uses conservative colors for contradictions and stale snapshots.

Examples:

# Generate kibi-report/index.html and open it
kibi report --open

# Write the single-file site to a CI staging directory
kibi report --output public/requirement-health

# Publish a focused report
kibi report --tag billing,security --output artifacts/kibi.html

For GitHub Pages, follow the copyable workflow in docs/examples/github/kibi-report.yml or run kibi init --github. That command scaffolds the same documented integration. Pull requests generate and validate kibi report, then upload kibi-pr-report; only the default branch publishes the canonical Pages site. Enable Settings → Pages → Source → GitHub Actions. Details, package-manager adaptations, owner-site URLs, and the badge-only opt-out are in GitHub badge + report.

Wrap the published badge image in a link to the report so clicking it opens the dashboard:

[![Kibi requirement health](https://OWNER.github.io/REPOSITORY/kibi-report/badge.svg)](https://OWNER.github.io/REPOSITORY/kibi-report/)

Actions artifacts expire and do not provide a stable anonymous URL, so the badge and its target should use the GitHub Pages deployment rather than the ordinary downloadable artifact. The Pages URL must be anonymously reachable for the badge to render in a public README; use an appropriate authenticated static host when the report must remain private.

kibi graph

Runs bounded graph traversal from one or more seed IDs.

Syntax:

kibi graph --from IDS [--relationships RELS] [--direction outgoing|incoming|both] [--depth N] [--entity-types TYPES] [--max-nodes N] [--max-edges N] [--format json|table]

Examples:

# Follow requirement links outward
kibi graph --from REQ-cli-gc --direction outgoing --depth 2 --format table

# Inspect both incoming and outgoing relationships
kibi graph --from REQ-mcp-search-discovery,TEST-mcp-search-discovery --direction both --depth 2 --format json

kibi check

Validates knowledge base integrity and runs inference rules.

Behavior:

• Validates required fields are present
• Checks requirement coverage (must-priority rules)
• Detects dangling references (entities that reference non-existent IDs)
• Detects cycles in dependency graphs
• Supports strict advisory modeling checks (strict-fact-shape, strict-req-fact-pairing, predicate-verifiability, proof-contract-symbols) that run by default as non-blocking qualityDiagnostics, and default-off migration diagnostics (strict-readiness, semantic-completeness) that run only when explicitly selected with --rules. Canonical rules always populate blocking violations[]. --rules is an invocation-time diagnostic filter only; leftover .kb/config.json cannot disable canonical checks. proof-contract-symbols reports unresolved required_proofs.symbol_id values, type-shape required proofs, and proof_bindings.source_file disagreement with the named symbol sourceFile. Kibi does not infer TEST names from filenames.
• Runs vocabulary-convergence checks by default, all advisory and non-blocking (see Vocabulary convergence checks): domain-redundancy, subject-key-identity, subject-key-shape, entity-id-style, predicate-schema-conformance (warnings) and domain-implication, ontology-quality (info).
• With --staged, inventories every index path before analysis. TypeScript and JavaScript keep their blocking symbol checks; Kibi metadata is validated through its typed lanes; every other readable UTF-8 text file receives advisory file-level ownership and impact-evidence checks.
• Staged deletions and renames retain committed content and ownership for removal review. Binary blobs, unsupported encodings, symlinks, and submodules are reported with explicit skipped reasons and remain non-blocking.
• Reports blocking violations[] with actionable suggestions and additive qualityDiagnostics[] audit signals for modeling quality, coverage depth, broad requirements, duplicate coordinates, symbol fanout, and strict-fact review
• When .kb/usage.log exists, an unfiltered check also turns failed or insufficient kibi.telemetry-acceptance.v1 metrics into ranked, non-blocking category: telemetry quality diagnostics; a missing log is skipped because diagnostic logging is opt-in
• Keeps advisory quality diagnostics non-blocking by default: review, info, and non-blocking warning diagnostics do not change the exit code; hard violations, severity: "error", or blocking: true still fail the check

Flags:

• --staged - Only check staged files (not whole repo)
• --kb-path <path> - Path to KB directory (optional)
• --rules <rule1,rule2> - Comma-separated list of rules to run (optional)
• --min-links <N> - Minimum requirement links per symbol for staged traceability (default: 1)
• --dry-run - Show staged-traceability effects without modifying files
• --format json|text - Output structured JSON for integrations such as OpenCode scheduled checks, or human-readable text output (default: text)

Staged Impact Evidence

When kibi check --staged reports kibi_impact_evidence_missing, first use Kibi discovery (kb_search, then kb_query) through visible MCP tools or trusted CLI JSON routes to inspect existing requirements, scenarios, tests, facts, and symbols for the edited source file. If the edit changes behavior, update the KB through either peer surface and also stage tracked evidence that the commit can carry: related entity markdown under .kb/, authored .kb/symbols.yaml entries, or refreshed .kb/symbol-coordinates.yaml output.

Both kibi_impact_evidence_missing and symbols_manifest_stale carry Detail: lines that name the cause per file: how many symbols the extractor finds in the staged source content, how many the staged evidence covers, and exactly which symbols are missing from .kb/symbols.yaml (with their definition lines). When the Detail lines list uncovered symbols, fix the cause first — author .kb/symbols.yaml entries for those symbols (kibi upsert, with implements/covered_by links) — and only then refresh coordinates with kibi sync --refresh-symbol-coordinates; the same comparison drives the printed Suggestion:. Detail lines cap at six names per list with an … and N more marker.

KB writes through MCP or CLI JSON routes update branch state, but they do not automatically stage markdown or manifest files. The staged hook can only accept evidence present in the staged change-set, so run the required sync/authoring step and git add the tracked evidence before rerunning kibi check --staged.

Examples:

# Check entire KB
kibi check

# Export structured two-lane check output for automation
kibi check --format json

# Check only staged changes
kibi check --staged

# Run specific rules
kibi check --rules must-priority-coverage,no-dangling-refs

# Audit advisory strict-fact modeling without failing canonical health
kibi check --rules strict-fact-shape

# Audit strict requirement/fact pairing without failing canonical health
kibi check --rules strict-req-fact-pairing

# Audit predicate ontology links without failing canonical health
kibi check --rules predicate-verifiability

# Audit Prolog validation query plans
kibi check --rules query-plan-safety

# Audit requirement status vocabulary (catches ADR statuses on reqs)
kibi check --rules req-status-vocabulary

# Audit vocabulary convergence (duplicates, subject keys, prose-in-atoms)
kibi check --rules domain-redundancy,subject-key-identity,subject-key-shape,ontology-quality

Vocabulary convergence checks

Deduplication and contradiction checks only work when equivalent prose lands on the same subject, predicate, and arguments. These rules measure and nudge that convergence. They are advisory: findings are non-blocking qualityDiagnostics and never change the exit code. All of them are deterministic over the compiled KB (Prolog, plus TypeScript for predicate-schema-conformance, which also needs the built-in predicate catalog); none calls a plugin or the network.

Property values are compared after unit canonicalization: durations convert to seconds, data sizes to bytes (SI kB/MB, IEC KiB/MiB), and percentages to percent. The authored value is stored unchanged. Unknown or ambiguous units (KB, Mb, month) stay as written and are never equated with anything else.

A predicate_schema can close an argument's vocabulary: argument_constants lists the allowed values per argument name, and argument_aliases maps legacy spellings to one of them. Arguments without an entry stay open.

fact_kind: predicate_schema
predicate_name: check_finding_policy
argument_names: [rule, finding, severity]
argument_constants:
  severity: [warning, info]
argument_aliases:
  severity: { warn: warning }

kb_upsert rejects a predicate fact that uses an undeclared value or an alias (naming the constant to use), and kb_suggest_predicates binds aliases to their constant and leaves undeclared values unbound. Existing facts are converged by kibi migrate (below).

While editing, agents can run impact diagnostics through MCP kb_check({sourceFiles:[...], includeImpactDiagnostics:true, includeWorkingTreeDiff:true}) or the equivalent kibi check --input <file|-> JSON route. kibi check --staged remains the commit-time git-hook gate once files are staged.

Structured JSON output preserves the same two-lane model used by MCP: hard correctness failures appear under structuredContent.violations[], while advisory audit signals appear under structuredContent.qualityDiagnostics[]. For --staged, one envelope is emitted for every outcome. structuredContent.staged.files[] records each path's Git status, analysis depth, disposition, ownership, evidence, provider, and skipped reason; file-level advisory findings appear in structuredContent.diagnostics[]. Advisory-only output is still a successful check; integrations should inspect blocking and severity instead of treating every diagnostic as a failure.

See also: Staged Symbol Traceability for --staged usage details.

kibi doctor

Verifies environment setup and diagnostics.

Behavior:

• Checks SWI-Prolog installation and version
• Verifies .kb/ directory exists
• Validates .kb/manifest.json syntax
• Recognizes leftover .kb/config.json and recommends kibi migrate --yes
• Checks git repository presence
• Verifies git hooks are installed and executable, reading them from the directory Git uses (git rev-parse --git-path hooks)
• Fails when an installed kibi-managed hook section differs from what the running CLI installs ("Kibi-managed hook sections"), for example a pre-commit hook written before the generated-manifest gate
• Reports issues with remediation suggestions

Examples:

kibi doctor
kibi doctor --format json

JSON mode emits kibi.doctor.v1 with resolved CLI, core, and MCP versions and their entrypoint/package locations so release validation can prove which artifacts are executing.

Common Issues Found:

• SWI-Prolog not found → See install guide
• .kb/ missing → Run kibi init
• Git hooks missing → Run kibi init
• Git hooks use the legacy template without kibi CLI resolution → Run kibi init to regenerate them
• Kibi-managed hook sections outdated for this CLI → Run kibi init to refresh them (hooks are shared by every worktree of the repository)
• Config invalid → Check .kb/manifest.json syntax; leftover .kb/config.json is retired with kibi migrate --yes

Release package validation

Release validation packs the published packages in dependency order, verifies their compiled entrypoints and dependency ranges, and exercises isolated npm and pnpm consumers. Consumer repositories own their local update scripts and dependency overrides; Kibi does not rewrite a consumer's manifests or workspace configuration.

kibi usage-metrics

Reports adoption and quality metrics from .kb/usage.log.

Syntax:

kibi usage-metrics [--format json|table] [--limit N] [--require-acceptance]

Behavior:

• Reads .kb/usage.log from the current repository
• Summarizes tool usage, branch activity, and success/error outcomes
• Reports telemetry completeness and zero-result rates
• Shows kb_check violation trend entries and grouped kb_upsert error categories
• Limits the zero-result source-file leaderboard with --limit
• Adds a versioned kibi.telemetry-acceptance.v1 report over the latest 200 events. It measures telemetry completeness, advisor-before-requirement-write use, exact validation-before-upsert use, source-linked zero-result rate, proof-gap recovery, receipt freshness, and repeated mutation failures.
• Separates failed from insufficient_evidence: an empty, stale (older than seven days), future-dated, partial-coverage, or pre-field-upgrade log cannot pass merely because no failure was observable

Flags:

• --format json|table - Output format (default: table)
• --limit N - Maximum number of top zero-result source files to include (default: 10)
• --require-acceptance - Exit non-zero unless the acceptance status is exactly passed; the report is still printed for repair automation

Examples:

# Show the default table report
kibi usage-metrics

# Export the full report structure as JSON
kibi usage-metrics --format json

# Show only the top 5 zero-result source files
kibi usage-metrics --limit 5

# Enforce the telemetry report as a completion gate
kibi usage-metrics --format json --require-acceptance

Notes:

• Returns an error if .kb/usage.log does not exist in the current repository
• --limit must be a positive integer
• Default thresholds are conservative and inspectable in acceptance.policy: at least 95% telemetry completeness, 100% advisor/preflight sequencing when applicable, no more than 20% zero-result source lookups, no receipt-specific gaps, and fewer than three consecutive failures for any mutation target

kibi usage-remediation

Builds a read-only kibi.telemetry-remediation.v1 report from .kb/usage.log.

kibi usage-remediation [--format json|table] [--limit N]

• Enumerates the exact log line, request, timestamp, tool, target, reason, and repair action for events behind failed or insufficient acceptance metrics
• Preserves session and actor identifiers when available; advisor and preflight evidence cannot match a write when both records expose different correlation identifiers
• Keeps missing complete coverage evidence as an explicit report-level item
• Sorts deterministically by repair rank, log line, and stable item identity
• Does not write to the knowledge base or usage log; --limit only bounds rendered table rows and never truncates JSON evidence
• The report uses exact canonical payload fingerprints for validation correlation when available and a deterministic legacy fingerprint otherwise. Requirement-advisor correlation requires the same requirement and, when both events expose it, the same semantic source hash.

kibi migrate

Previews or applies the structured branch migration plan. With no mutation flags, it is a read-only preview; --format json returns the complete kibi.migration-plan.v2 action graph.

Behavior:

• Upgrades entity schemas and internal storage formats
• Marks pre-existing coarse symbol links with granularity_reason: legacy-link when narrower exported symbols or class methods (ClassName.methodName) are already available
• Fixes legacy requirement modeling to follow strict fact-pairing rules
• Moves legacy documentation/ knowledge lanes and leftover .kb/config.json into the canonical .kb/ layout
• Replaces the pre-canonical blanket .kb/ gitignore stanza with derived-runtime ignores so migrated .kb/<lane>/ files are trackable
• Treats malformed .kb/config.json as a blocker instead of guessing documentation/ paths
• Writes .kb/manifest.json with the latest schemaVersion
• Offers predicate_schema_alignment actions for predicate-schema-conformance findings with a mechanical repair: moving a predicate fact to the only namespace whose schema matches its name and arity, and rewriting argument aliases to their declared constants (with the matching canonical_key). Each action is automatic, carries the exact kb_upsert input, and re-reads the fact before writing; a fact that changed since planning fails the action instead of being overwritten. Ambiguous namespaces and undeclared values stay review actions.
• Idempotent: safe to run if already on the latest version

Flags:

• --dry-run - Show what would be migrated without making changes
• --yes - Apply migration changes without prompting
• --format json|table - Render the structured plan or a concise table
• --apply-safe - Apply only approved deterministic actions
• --approved-plan-hash SHA256 - Required exact plan hash for --apply-safe
• --approved-action ID - Explicit automatic action ID (repeatable or comma-separated)

Example (predicate vocabulary):

kibi migrate --format json > plan.json        # review predicate_schema_alignment actions
kibi migrate --apply-safe --approved-plan-hash "$(jq -r .planHash plan.json)"

Notes:

• Use kibi status to check if a migration is pending for your branch.
• Safe application rejects stale hashes, blocked actions, review/operator actions, and actions omitted from --approved-action.
• Migration is recommended when upgrading kibi-cli or kibi-mcp packages.
• After migration, run kibi sync --refresh-symbol-coordinates if symbol coordinate diagnostics remain.

kibi gc

Garbage collects stale branch knowledge bases.

Behavior:

• Lists branch KBs that no longer exist in git
• Quarantines stale stores first; irreversible deletion requires explicit purge
• Keeps quarantined stores restorable during the retention window (30 days by default)
• Safe by default (dry-run mode)

Flags:

• --dry-run - Only list stale branches (default)
• --force - Quarantine stale branches (reversible)
• --purge - Permanently purge quarantined stores past retention
• --retention-days <n> - Retention window for purge (default: 30)

Examples:

# List stale branches (safe)
kibi gc --dry-run

# Quarantine stale branches
kibi gc --force

# Purge expired quarantined stores
kibi gc --purge --retention-days 30

Notes:

• Use --dry-run first to see what would be deleted
• Stale = an exact or legacy store whose branch is not a local Git head or worktree branch; remote-only refs do not keep stores live

kibi branch

Lists and manages branch knowledge bases.

Syntax:

kibi branch ensure
kibi branch migrate --from <legacy-branch> --to <active-branch> [--apply --approval-hash <sha256>]
kibi branch recover [--apply]
kibi branch restore --branch <branch> [--apply]

Arguments:

• ensure - Ensure the active branch has a branch-local KB snapshot
• migrate - Preview (or, with --apply, atomically move) a legacy branch KB into the exact active Git branch namespace
• recover - Preview (or, with --apply, rebuild) an incomplete or unreadable exact branch store from authored sources while preserving the original bytes
• restore - Preview (or, with --apply, restore) the newest quarantined exact branch store within its retention window

Flags:

• --to <active-branch> - Explicit exact Git identity receiving a legacy-store migration; it must match the active branch
• --approval-hash <sha256> - Required hash copied from the preview; source bytes and identities must still match exactly

Behavior:

• Ensures the active git branch has a compiled KB under .kb/branches/<exact-ref-sha256>/branch.json
• A missing exact branch store is compiled from the current checkout's tracked sources; no other branch store is copied
• Branch names are never normalized; master and main are separate namespaces and remote-only refs do not keep stores live
• migrate previews by default, stops an attached branch engine before applying, requires the exact target namespace to be absent, and preserves journals/audit/cache files.
• migrate is an explicit old/new legacy-literal-path migration. It rejects inferred renames and arbitrary branch-store cloning. The old and new identities may be equal when moving a literal store for the current branch into its hashed path.
• recover publishes only after a clean rebuild has succeeded, moves the prior store to .kb/recovery/<branch>/..., and writes an audit record. It never renames a Git branch.

Examples:

# Ensure the current branch has a KB
kibi branch ensure

# Preview then apply a legacy literal-store migration while on the target branch
kibi branch migrate --from old-ref --to feature/target
kibi branch migrate --from old-ref --to feature/target --apply --approval-hash <preview-hash>

# Preview then recover an unreadable store for the active exact branch
kibi branch recover
kibi branch recover --apply

HT|## kibi skills QN| MV|Manage and inspect bundled agent skills. Skills are reusable Markdown guidance packages shipped with Kibi. QN| XW|Behavior: TY|- Lists available bundled skills TZ|- Loads a skill's manifest and body BH|- Reads individual resources declared by a skill JM|- Validates a local skill bundle directory QN| XQ|Subcommands: PJ| BV|bash QN|kibi skills list [--format json|table] SV|kibi skills load <id> [--format json|markdown] HY|kibi skills read <id> <resource> [--format text|json] QB|kibi skills validate <path> [--format json|table] BP| ZS| JK|Arguments: JB|- list - Show all bundled skills with ID, name, version, and description XY|- load <id> - Load a skill by its bundled ID. Returns the skill body and manifest. BJ|- read <id> <resource> - Read a specific resource file declared in the skill manifest PX|- validate <path> - Validate a local skill bundle directory against the skill schema PS| XQ|Flags: PX|- --format json|table - Output format for list and validate (default: table) YR|- --format json|markdown - Output format for load (default: markdown) SP|- --format text|json - Output format for read (default: text) PT| MT|Examples: BV|bash QQ|# List all bundled skills NZ|kibi skills list TM| MS|# Load the canonical usage skill as markdown NB|kibi skills load kibi-usage --format markdown NZ| VW|# Read a specific resource from a skill MB|kibi skills read kibi-usage resources/fact-lanes.md --format text QJ| PY| HX|Notes: YS|- Skills are bundled with Kibi. Remote installation, marketplace, and script execution are not supported in v1. QT|- OpenCode is an adapter for skill discovery, not the source of truth. The bundled skill set is authoritative.

• Generic MCP/CLI agents should start with generic-agent onboarding and load kibi-usage. Do not copy a long prompt as a substitute for skill discovery. XB

Staged Symbol Traceability

kibi check-generated --staged compares the staged .kb/symbols.yaml and .kb/symbol-coordinates.yaml bytes with the output of a coordinate refresh computed from the exact Git index. It fails if either manifest would change or if the index changes while it runs. The command does not alter the index or working tree. Run kibi sync --refresh-symbol-coordinates, review the diff, then stage only the intended hunks (git add -p) before retrying. CI runs the full check before prove --all. The installed pre-commit hook uses --changed-only to avoid regeneration when staged paths cannot affect symbol manifests; commits touching symbol sources or manifests run the full check. An initialized repository with no symbols has no coordinate artifact to refresh, so its first commit is allowed without that file.

The kibi check --staged command inventories every staged path and enforces traceability on code before commit.

Purpose: Every new or modified code symbol (function, class, method, accessor, behavioral class property, or module) must be explicitly linked to at least one requirement before it can be committed. This prevents "orphan" code from being merged and catches edits hidden behind broad class/module links when a narrower changed anchor exists.

Workflow Options:

1. Relationship-based (Preferred for Test/e2e): Model the code as a symbol in your manifest (e.g., .kb/symbols.yaml), link it to a TEST-* entity with executable_for to establish its identity. The canonical traceability chain is REQ-<area>-<behavior> → SCEN-<area>-<behavior> → TEST-<area>-<behavior>. Use covered_by to link symbols to the tests that exercise them. This satisfies the staged check without modifying source code. Note that physical symbol coordinates are maintained separately in .kb/symbol-coordinates.yaml and must be refreshed via kibi sync --refresh-symbol-coordinates when code changes.
2. Comment-based (Optional Shortcut): Add an inline // implements REQ-<area>-<behavior> comment. This remains backward-compatible and useful for quick code-only changes.

How to use:

# Check staged files for traceability coverage
kibi check --staged

This command reads blob content from the Git index rather than the working tree. It reports any new or modified TypeScript/JavaScript symbols that do not have requirement links (either via inline comments or explicit KB relationships). It also reports stale symbol-coordinate evidence and symbol_granularity_violation when a changed behavioral member such as UploadPageComponent.processingProgressLabel is covered only by a coarse class/module relationship without an audited granularity_reason. If violations are found and this is run as a pre-commit hook, the commit will be blocked.

Readable UTF-8 files outside the TypeScript/JavaScript and Kibi metadata lanes receive advisory file-level checks. This includes Python, shell scripts, YAML and Compose files, Dockerfiles, Markdown, JSON, and other text formats. Kibi resolves ownership only from real source-linked symbol entities and typed implements relationships in committed knowledge plus the staged KB changes. Unstaged KB edits and unrelated staged entities do not satisfy the advisory check.

The text and JSON output include the complete path inventory, counts by analysis depth, and an explicit reason for skipped content. “No staged files found” is reserved for an empty Git index. Binary blobs, non-UTF-8 text, symlinks, and submodules are reported but do not block the commit.

The staged CLI gate does not prove that linked prose still matches the source edit. Use an impact-enabled kb_check through MCP or CLI JSON mode while editing to get symbol_semantic_review_needed guidance and inspect linked requirements/scenarios/tests before deciding whether to update KB entities.

Quality diagnostics may also appear during full or staged checks. They are designed to surface auditability problems automatically without creating a new command agents must remember: broad requirement reviews, multi-requirement symbol fanout, mixed-purpose class/component reviews, duplicate symbol-coordinate reviews, status misuse, strict-fact modeling gaps, and coverage-depth labels are review signals unless explicitly marked blocking.

Scope Note: Staged symbol checks handle explicitly modeled symbols and extracted TypeScript/JavaScript anchors, including exported class methods, accessors, and behavior-bearing class properties. Other readable text currently receives file-level analysis. Automatic extraction of framework-specific test() or it() callbacks is not currently supported.

Inline Directive Syntax (Optional):

Link a code symbol to a requirement by adding a comment:

export function myFunc() { } // implements REQ-cli-gc

Link to multiple requirements:

export class MyClass { } // implements REQ-cli-gc, REQ-cli-check

Analysis depth:

• Symbol-level: TypeScript and JavaScript (.ts, .tsx, .js, .jsx, .mts, .cts, .mjs, .cjs)
• Metadata: Kibi entity Markdown, symbol manifests, coordinate manifests, relationship shards, and .kb/manifest.json
• Advisory file-level: all other readable UTF-8 files
• Explicitly skipped: binary blobs, unsupported encodings, symlinks, and submodules

CLI Flags for staged checking:

• --staged - Only check staged files
• --min-links <N> - Minimum requirement links per symbol (default: 1)
• --kb-path <path> - Path to KB directory
• --rules <rule1,rule2> - Specific rules to run
• --dry-run - Show what would be blocked without blocking commit

See also:

• Troubleshooting - Hook repair and remediation
• AGENTS.md - Agent-specific workflows

For detailed system architecture, see architecture.md For entity and relationship schemas, see entity-schema.md For MCP server reference, see mcp-reference.md