kibi-cli 2.15.0 → 2.16.0

package/src/public/operations/check-executor.ts

@@ -1,4 +1,10 @@
 import { runAggregatedChecks } from "../../commands/aggregated-checks.js";
+import { resolveBranchAttachment } from "../../utils/branch-resolver.js";
+import {
+  BRANCH_STORE_NOT_COMPILED_RULE,
+  inspectBranchStore,
+  uncompiledBranchStoreReason,
+} from "../../utils/branch-store.js";
 /*
  Kibi — repo-local, per-branch, queryable long-term memory for software projects
  Copyright (C) 2026 Piotr Franczyk
@@ -74,6 +80,14 @@ export {
 
 export type CheckExecutionOptions = {
   readonly collectFullQualityDiagnosticsForExplicitRules?: boolean;
+  /**
+   * The engine reads the current branch's store although the context carries
+   * no branch attachment (the `kibi check` engine path). A context with a
+   * branch attachment (the CLI and MCP runtimes) implies it; without either,
+   * the attached store is unknown (an explicit --kb-path store or an injected
+   * test store) and the branch-store compilation check is skipped.
+   */
+  readonly branchStoreAttached?: boolean;
 };
 
 function requireProlog(context: OperationContext): PrologPort {
@@ -126,6 +140,50 @@ async function readStatusMigrationPlan(
   }
 }
 
+/**
+ * The one finding for a branch whose store was never compiled while .kb/
+ * holds authored sources. Every store-backed rule would read an empty KB
+ * (source-relationship-parity alone reports each authored relationship as
+ * missing), so kb_check reports this instead of any of them.
+ */
+// implements REQ-cli-status-pre-first-sync
+export function uncompiledBranchStoreViolation(
+  context: OperationContext,
+  workspaceRoot: string,
+): Violation | null {
+  let attachment: ReturnType<typeof resolveBranchAttachment>;
+  try {
+    attachment =
+      context.branchAttachment ?? resolveBranchAttachment(workspaceRoot);
+  } catch {
+    return null;
+  }
+  if ("error" in attachment) return null;
+  const store = inspectBranchStore(workspaceRoot, attachment.kbBranch);
+  const reason = uncompiledBranchStoreReason(
+    workspaceRoot,
+    store,
+    attachment.kbBranch,
+  );
+  if (reason === null) return null;
+  return {
+    rule: BRANCH_STORE_NOT_COMPILED_RULE,
+    entityId: attachment.kbBranch,
+    description: String(reason.detail),
+    suggestion:
+      "Run kibi sync to compile this branch's store from the authored .kb/ sources (or apply the branch-store-compile action of the returned migrationPlan with kb_apply_plan), then rerun kb_check. Run kibi init once to install the git hooks that compile a new branch on checkout.",
+    source: store.path,
+    evidence: {
+      store: { state: store.state, path: store.path },
+      authoredSources: reason.authoredSources,
+      ...(reason.generation !== undefined
+        ? { generation: reason.generation }
+        : {}),
+      remediation: reason.remediation,
+    },
+  };
+}
+
 // implements REQ-kibi-operation-interface-parity, REQ-002
 export async function executeCheck(
   args: CheckInput,
@@ -154,6 +212,53 @@ export async function executeCheck(
         ? { maxDiagnostics: args.maxDiagnostics }
         : {};
 
+    const uncompiled =
+      context.branchAttachment !== undefined ||
+      options.branchStoreAttached === true
+        ? uncompiledBranchStoreViolation(context, workspaceRoot)
+        : null;
+    if (uncompiled !== null) {
+      const violations = [uncompiled];
+      const statusPlan = await readStatusMigrationPlan(context);
+      const migrationPlan = await migrationPlanForCheck(
+        context,
+        violations,
+        [],
+        statusPlan,
+      );
+      return {
+        content: [
+          {
+            type: "text",
+            text: buildSummary({
+              violations,
+              impactResult,
+              qualityDiagnostics: [],
+            }),
+          },
+        ],
+        structuredContent: buildStructuredContent({
+          violations,
+          diagnostics: [
+            {
+              category: "SYNC_ERROR",
+              severity: "error",
+              message: uncompiled.description,
+              ...(uncompiled.source !== undefined
+                ? { file: uncompiled.source }
+                : {}),
+              ...(uncompiled.suggestion !== undefined
+                ? { suggestion: uncompiled.suggestion }
+                : {}),
+            },
+          ],
+          qualityDiagnostics: [],
+          impactResult,
+          migrationPlan,
+        }),
+      };
+    }
+
     if (rulesAllowlist.size === 0) {
       const qualityDiagnostics =
         hasExplicitRules &&

package/src/public/operations/discovery-executors.ts

@@ -16,10 +16,12 @@ import { rankEntities } from "../../search-ranking.js";
 import type { SearchMatch } from "../../search-ranking.js";
 import { resolveBranchAttachment } from "../../utils/branch-resolver.js";
 import {
+  BRANCH_STORE_NOT_COMPILED,
   type BranchStoreInspection,
   branchStoreReason,
   inspectBranchStore,
   storeLockJournalReason,
+  uncompiledBranchStoreReason,
 } from "../../utils/branch-store.js";
 import {
   loadEntities,
@@ -459,7 +461,17 @@ export async function executeStatus(
       }
     const snapshotEvidence = await readWorkspaceSnapshot(context);
     const existingReasons = payload.staleReasons ?? [];
-    const storeReason = branchStoreReason(store);
+    // implements REQ-cli-status-pre-first-sync
+    // A missing or empty store beside authored sources gets the one reason
+    // whose remediation works (kibi sync); `kibi branch ensure` alone would
+    // leave the store empty.
+    const storeReason =
+      uncompiledBranchStoreReason(
+        context.workspaceRoot,
+        store,
+        attachment.kbBranch,
+      ) ?? branchStoreReason(store);
+    const storeUncompiled = storeReason?.code === BRANCH_STORE_NOT_COMPILED;
     const lockReason = storeLockJournalReason(store.path);
     const compilerReason = compilerFingerprintReason(store.path);
     const engineReason = engineStatus
@@ -495,6 +507,11 @@ export async function executeStatus(
       // Source hashes can all match while the compilation itself is lossy, so
       // a compiler contract change alone makes the store stale.
       ...(compilerReason ? { syncState: "stale", dirty: true } : {}),
+      // An empty store has no stale file to report, yet nothing in it is
+      // current: the authored sources were never compiled.
+      ...(storeUncompiled && store.state === "healthy"
+        ? { syncState: "stale", dirty: true }
+        : {}),
       branchAttachment: attachment,
       branchStore: store,
       ...(engineStatus ? { engineStatus } : {}),
@@ -644,7 +661,7 @@ export async function executeStatus(
       content: [
         {
           type: "text",
-          text: `Branch ${payload.branch} is ${payload.syncState} (snapshot ${payload.snapshotId}, dirty=${payload.dirty}, proofSnapshot=${enrichedPayload.proofSnapshot})`,
+          text: `Branch ${payload.branch} is ${enrichedPayload.syncState} (snapshot ${payload.snapshotId}, dirty=${enrichedPayload.dirty}, proofSnapshot=${enrichedPayload.proofSnapshot})${storeUncompiled ? `. Blocking: ${String(storeReason?.detail)} Run kibi sync.` : ""}`,
         },
       ],
       structuredContent: statusWithPlan,

package/src/public/operations/migration-plan.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import * as path from "node:path";
+import { BRANCH_STORE_NOT_COMPILED } from "../../utils/branch-store.js";
 import { legacyConfigExists } from "../../utils/config.js";
 import { readKbManifestStatus } from "../../utils/kb-manifest.js";
 import {
@@ -744,8 +745,42 @@ export function buildActionsFromStatus(input: {
     );
   }
 
+  // implements REQ-cli-status-pre-first-sync
+  // A branch store that was never compiled while .kb/ holds authored sources
+  // is fixed only by compiling it: `kibi branch ensure` alone leaves an empty
+  // manifest. The compile step runs after the store exists and after any
+  // schema migration, so it compiles the migrated sources.
+  const uncompiled = (input.staleReasons ?? []).find(
+    (reason) => reason.code === BRANCH_STORE_NOT_COMPILED,
+  );
+  if (uncompiled !== undefined) {
+    actions.push(
+      migrationAction({
+        id: "branch-store-compile",
+        code: BRANCH_STORE_NOT_COMPILED,
+        category: "storage",
+        safety: "automatic",
+        invocation: { kind: "cli", command_argv: ["kibi", "sync"] },
+        affectedFiles: [
+          typeof store?.path === "string" ? store.path : ".kb/branches",
+        ],
+        evidence: { reason: uncompiled },
+        dependsOn: actions
+          .map((action) => action.id)
+          .filter(
+            (id) =>
+              id === "branch-store-ensure" || id === "schema-config-upgrade",
+          ),
+        postconditions: [{ branchStore: "compiled" }],
+        autoApplicable: true,
+      }),
+    );
+  }
+
   for (const reason of input.staleReasons ?? []) {
     const code = typeof reason.code === "string" ? reason.code : "stale_source";
+    // Planned above as an automatic compile step, not a review.
+    if (code === BRANCH_STORE_NOT_COMPILED) continue;
     const file = typeof reason.path === "string" ? reason.path : "";
     actions.push(
       migrationAction({

package/src/public/operations/specs/check-rules.generated.ts

@@ -15,6 +15,7 @@ export const SELECTABLE_RULE_NAMES: readonly string[] = [
   "symbol-traceability",
   "no-dangling-refs",
   "source-relationship-parity",
+  "branch-store-not-compiled",
   "source-path-dangling",
   "no-cycles",
   "required-fields",
@@ -61,4 +62,4 @@ export const SELECTABLE_RULE_NAMES: readonly string[] = [
 // implements REQ-006
 /** Comma-separated "Allowed:" fragment for the kb_check rules description. */
 export const SELECTABLE_RULES_ALLOWED =
-  "must-priority-coverage, symbol-coverage, symbol-traceability, no-dangling-refs, source-relationship-parity, source-path-dangling, no-cycles, required-fields, deprecated-adr-no-successor, superseded-requirement-open, scenario-feasibility, scenario-feasibility-unknown, exception-claim-keys, numeric-string-value, rule-key-arguments-missing, domain-contradictions, logic-coverage, rule-safety, rule-verifiability, query-plan-safety, req-status-vocabulary, strict-fact-shape, strict-req-fact-pairing, predicate-verifiability, strict-readiness, semantic-completeness, related-requirement-unmodeled, proof-contract-symbols, entity-id-style, domain-redundancy, domain-implication, subject-key-identity, subject-key-shape, ontology-quality, exception-unapproved, exception-approval-self-attested, agent-requirement-unapproved, requirement-rationale-missing, symbol-owner-superseded, adr-unlinked, adr-proposed, predicate-schema-conformance, entity-context-missing, entity-context-acknowledged, policy-ownership, policy-markers";
+  "must-priority-coverage, symbol-coverage, symbol-traceability, no-dangling-refs, source-relationship-parity, branch-store-not-compiled, source-path-dangling, no-cycles, required-fields, deprecated-adr-no-successor, superseded-requirement-open, scenario-feasibility, scenario-feasibility-unknown, exception-claim-keys, numeric-string-value, rule-key-arguments-missing, domain-contradictions, logic-coverage, rule-safety, rule-verifiability, query-plan-safety, req-status-vocabulary, strict-fact-shape, strict-req-fact-pairing, predicate-verifiability, strict-readiness, semantic-completeness, related-requirement-unmodeled, proof-contract-symbols, entity-id-style, domain-redundancy, domain-implication, subject-key-identity, subject-key-shape, ontology-quality, exception-unapproved, exception-approval-self-attested, agent-requirement-unapproved, requirement-rationale-missing, symbol-owner-superseded, adr-unlinked, adr-proposed, predicate-schema-conformance, entity-context-missing, entity-context-acknowledged, policy-ownership, policy-markers";

package/src/public/operations/specs/composite.ts

@@ -29,17 +29,76 @@ function requiredFields(spec: {
   return Array.isArray(required) ? (required as string[]) : [];
 }
 
+type CompositeRoute = {
+  readonly name?: string;
+  readonly execute: Executor;
+  readonly businessInputSchema: Readonly<Record<string, unknown>>;
+};
+
+/**
+ * Per route, the parameters another route of the same composite owns that
+ * mean the same thing here under another name. kb_model mode requirement
+ * takes the claim's subject as subjectKey; mode predicates takes it as
+ * subjectHint.
+ */
+const EQUIVALENT_PARAMETERS: Readonly<
+  Record<string, Readonly<Record<string, string>>>
+> = {
+  kb_suggest_predicates: { subjectKey: "subjectHint" },
+  kb_model_requirement: { subjectHint: "subjectKey" },
+};
+
+/** Routed operations whose `warnings` are `{ kind, message, nextAction }`. */
+const RECORD_WARNING_OPERATIONS = new Set(["kb_model_requirement"]);
+
+// implements REQ-kibi-mcp-tool-consolidation
+/**
+ * A composite accepts every route's parameters, so a parameter of another
+ * route passes schema validation and the chosen route silently ignores it.
+ * Name each one instead, with the parameter this route uses for the same
+ * thing when there is one.
+ */
+export function foreignParameterWarnings(
+  selector: "action" | "mode",
+  choice: string,
+  routes: Readonly<Record<string, CompositeRoute>>,
+  rest: Readonly<Record<string, unknown>>,
+): Array<{ parameter: string; message: string; nextAction: string }> {
+  const route = routes[choice];
+  if (route === undefined) return [];
+  const own = new Set(Object.keys(properties(route)));
+  const equivalents =
+    route.name === undefined ? {} : (EQUIVALENT_PARAMETERS[route.name] ?? {});
+  const warnings: Array<{
+    parameter: string;
+    message: string;
+    nextAction: string;
+  }> = [];
+  for (const parameter of Object.keys(rest)) {
+    if (own.has(parameter) || rest[parameter] === undefined) continue;
+    const owners = Object.entries(routes)
+      .filter(
+        ([other, otherRoute]) =>
+          other !== choice && parameter in properties(otherRoute),
+      )
+      .map(([other]) => `${selector}: ${other}`);
+    if (owners.length === 0) continue;
+    const equivalent = equivalents[parameter];
+    warnings.push({
+      parameter,
+      message: `${parameter} is a ${owners.join(" / ")} argument; ${selector}: ${choice} ignored it.`,
+      nextAction:
+        equivalent !== undefined
+          ? `Use ${equivalent} in ${selector}: ${choice}.`
+          : `Drop ${parameter}, or switch to ${owners.join(" / ")} if that is what you meant.`,
+    });
+  }
+  return warnings;
+}
+
 export async function dispatchComposite(
   selector: "action" | "mode",
-  routes: Readonly<
-    Record<
-      string,
-      {
-        readonly execute: Executor;
-        readonly businessInputSchema: Readonly<Record<string, unknown>>;
-      }
-    >
-  >,
+  routes: Readonly<Record<string, CompositeRoute>>,
   input: Readonly<Record<string, unknown>>,
   context: OperationContext,
 ): Promise<OperationResult<Record<string, unknown>>> {
@@ -69,9 +128,49 @@ export async function dispatchComposite(
     wrapped && Array.isArray(result.content)
       ? (result.content as OperationResult["content"])
       : [{ type: "text", text: `${selector} ${String(choice)} completed` }];
+  const ignored = foreignParameterWarnings(
+    selector,
+    String(choice),
+    routes,
+    rest,
+  );
+  if (ignored.length === 0) {
+    return {
+      content,
+      structuredContent: { [selector]: choice, ...payload },
+    };
+  }
+  // The routed payload's own warnings list carries them, in its own shape;
+  // a payload without one gets them in the text content only.
+  const asRecords =
+    route.name !== undefined && RECORD_WARNING_OPERATIONS.has(route.name);
+  const routedWarnings = Array.isArray(payload.warnings)
+    ? {
+        warnings: [
+          ...payload.warnings,
+          ...ignored.map((warning) =>
+            asRecords
+              ? {
+                  kind: "parameter_ignored",
+                  message: warning.message,
+                  nextAction: warning.nextAction,
+                }
+              : `${warning.message} ${warning.nextAction}`,
+          ),
+        ],
+      }
+    : {};
   return {
-    content,
-    structuredContent: { [selector]: choice, ...payload },
+    content: [
+      ...content,
+      {
+        type: "text",
+        text: ignored
+          .map((warning) => `${warning.message} ${warning.nextAction}`)
+          .join("\n"),
+      },
+    ],
+    structuredContent: { [selector]: choice, ...payload, ...routedWarnings },
   };
 }
 

package/src/public/operations/specs/modeling.ts

@@ -78,7 +78,7 @@ export const modelRequirementSpec = {
       requirementId: {
         type: "string",
         description:
-          "Optional existing requirement ID to receive the requires_rule relationship.",
+          "Optional requirement ID. The strict write set updates this requirement instead of minting a REQ-AUTO id, and a typed logic rule attaches its requires_rule relationship to it.",
       },
       claimKey: {
         type: "string",

package/src/public/skills/kibi-bootstrap/SKILL.md

@@ -2,7 +2,7 @@
 id: kibi-bootstrap
 name: kibi-bootstrap
 description: "Use for any Kibi bootstrap or onboarding task: seeding a new or thin knowledge base; reviewing a bootstrap or onboarding plan, preview, or evidence; judging approval readiness or coverage; diagnosing a blocked, partial, or failed bootstrap or its repair; applying an approved bootstrap plan; or asking the human which knowledge sources hold intent. Covers kb_status first, source interview, cited intent claims, read-only kb_plan_bootstrap preview, explicit approval, exact-plan kb_apply_plan, and repair-safe close-out."
-version: 3.10.0
+version: 3.11.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -46,6 +46,7 @@ Seed branch-local Kibi knowledge from cited product intent, without creating a p
     - **Scenarios.** Write scenarios from the cited ticket's acceptance criteria, one scenario per criterion, not bulk drafts from the requirement title; ask the human when the source states none. Give each a plain title, the scenario prose in `document.body` (never in `properties`), and `assumes` links to the `property_value` facts whose values the scenario relies on. Set `expects` only when the scenario links `assumes` facts (or its criterion names concrete values that become them); `expects` without `assumes` only yields a feasibility-unknown warning, so a draft tagged `needs-human-review` omits `expects`. Then link the requirement with `specified_by` (upsert the `req` with its stored `title`, a `status` and that relationship only). Example: criterion "Given an annotation in draft state, when the user deletes it, the draft is cleared" becomes `{"type":"scenario","id":"SCEN-annotation-delete-clears-draft","properties":{"title":"Deleting a draft annotation clears the draft","status":"active","expects":"success"},"document":{"body":"Given an annotation in draft state, when the user deletes it, then the draft is cleared and nothing is published.\n\nThe acceptance criterion comes from the cited ticket; reviewers asked for it so a deleted draft never reappears after reload.\n"},"relationships":[{"type":"assumes","from":"SCEN-annotation-delete-clears-draft","to":"FACT-annotation-state-draft"}]}`, where the assumed fact is a `property_value` (`annotation.state` `eq` `draft`). Link existing tests that exercise it; never invent test evidence.
     - **Predicates.** Run `kb_model` with `mode: "predicates"` and `requirementId` on each persisted requirement and apply a returned plan with `requires_predicate` to its `relationshipTarget` (the planned `FACT-PRED-…` id, never a `SUGGEST-…` candidate id), or record the `review:ontology-gap` observation it returns, with its prose in `document.body`. A non-empty `existingGrounding` means the bootstrap already grounded that claim: on `replace_grounding` leave it unless the human wants the `replacementPlan` swap; on `provide_argument_bindings` retry with the listed arguments bound; on `record_ontology_gap` still write the returned gap observation, which is not a grounding link. Count what `kb_query` shows afterwards, not the calls you made.
     - **Unrecorded ambiguity.** Record any conflict or open question you found but did not declare in step 3 as a cited `fact_kind: observation` tagged `review:conflict` or `review:open-question`.
+    - **Proof integration.** Run `kibi proof inspect --json`. When it returns an `integrationPlan` (a `command` integration for the detected test runner), show the human the proposed command and `contractDefaults`, and on approval apply that exact plan with `kb_apply_plan` (`plan`, `approvedPlanHash` = its `planHash`, `approvedActionIds`); it writes `.kb/proof/integrations.json`, which you never hand-write. With no runner detected, report that proof stays deferred. Proof-bearing tests then name the integration in `proof_contract.integration`, and `kibi prove` records their evidence.
     Finish with `kb_check` and `kb_status`.
 12. **Report** calls made, result statuses, applied scope, what step 11 authored, gaps, and follow-ups. Classify as complete, partial, awaiting approval, or blocked.
 

package/src/public/skills/kibi-usage/SKILL.md

@@ -2,7 +2,7 @@
 id: kibi-usage
 name: Kibi Usage
 description: Use Kibi's source-first, exact-Git, migration-aware, proof-aware operations safely across MCP or the trusted local CLI, including partial completion repair.
-version: 2.11.0
+version: 2.12.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -219,11 +219,19 @@ authored. Each one is the order the write path accepts.
    `semantic_inventory_version`, `semantic_source_field` and
    `semantic_source_hash`, the prose into `semantic_text`, `propositions`
    into `semantic_inventory` and the assertive `claim_key`s into
-   `logic_claims`. `kb_model` mode `predicates` per clause; `kb_upsert` the
-   returned `applyPlan` fact first (it carries the clause's `claim_key`).
-   Then write the requirement in one `kb_upsert` with the ledger (that
-   clause `status: modeled`), a sectioned `document.body`, `constrains` to
-   the subject fact and `requires_predicate` to `relationshipTarget`. A
+   `logic_claims`. Reuse (or `kb_upsert`) the subject fact, then call
+   `kb_model` mode `predicates` per clause with `subjectHint` set to that
+   subject fact's `subject_key`: the requirement constrains nothing yet, so
+   the hint is the planned subject and the planned fact gets its
+   `subject_key` (`subjectKey` is a mode `requirement` parameter; mode
+   `predicates` ignores it and warns). `kb_upsert` the returned `applyPlan`
+   fact first (it carries the clause's `claim_key`). Then write the
+   requirement in one `kb_upsert` with the ledger (that clause `status:
+   modeled`), a sectioned `document.body`, `constrains` to the subject
+   fact, `requires_predicate` to `relationshipTarget` and `specified_by` to
+   its scenario: `specified_by` (req → scenario) is sent in the
+   requirement's write, never in the scenario's, so create the scenario
+   first. A
    `modeled` entry and its grounding link must arrive in the same write
    (`modeled semantic_inventory entries (n) must equal logical grounding
    relationships (m)`); a clause not grounded yet stays `status: missing`

package/src/public/skills/kibi-usage/resources/proof.md

@@ -54,7 +54,16 @@ Provenance lives in `proof_bindings`; the contract stays semantic.
 ## Integration configuration
 
 `.kb/proof/integrations.json` (`kibi.proof-integration.v1`) is tracked,
-Kibi-managed configuration describing evidence production only:
+Kibi-managed configuration describing evidence production only. Never
+hand-write it: `kibi proof inspect --json` proposes a `command` integration
+for the detected test runner (the `package.json` `test` script first) and
+returns `integrationPlan`, a hash-bound `kibi.migration-plan.v2`, plus the
+`contractDefaults` a proof-bearing test's `proof_contract` uses. Show the
+proposal to the human, then apply the plan with `kb_apply_plan` (or
+`kibi apply-plan --input -`) passing `plan`, `approvedPlanHash` (the plan's
+`planHash`) and `approvedActionIds`. Once the file exists, a create plan is
+refused; `kibi proof inspect --update <id> --json` plans adding or replacing
+one named integration.
 
 - `producer: command` — Kibi synthesizes the envelope from the process
   outcome; obligations are bound with `aggregate_run` provenance and the
@@ -82,8 +91,11 @@ effective fingerprint and do.
 
 ## Common rejections
 
-- `No proof integration configuration` — bootstrap has not configured proof
-  for this repository yet; do not hand-wave, run the bootstrap proof step.
+- `No proof integration configuration` — proof is not configured for this
+  repository yet; run `kibi proof inspect --json`, review its
+  `integrationPlan` and apply it with `kb_apply_plan`.
+- `integration '<id>' ... is not configured` — the test names an integration
+  the file lacks; plan it with `kibi proof inspect --update <id> --json`.
 - `captured snapshot is not the live workspace snapshot` — the tree changed
   between capture and ingest; re-run `kibi prove`.
 - `artifact command_argv does not match the configured command` — the