kibi-cli 2.26.3 → 2.27.0

package/dist/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.19.0
+version: 2.20.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -410,6 +410,16 @@ Conditional clauses ("only when", "only if", "must not ... unless") compile
 into typed `forbid` rules linked by `requires_rule`, not property facts; one
 `kb_model` or `kb_compile_intent` cannot translate stays an `ontology_gap`.
 
+`kb_compile_intent` reports `contradictionAnalysis.outcome: no_conflict` only
+when it could check: Prolog compares only requirements with logic links. When
+the intent is unmodeled or a related current requirement is prose only, the
+outcome is `unresolved` with `reasons` and up to five `reviewCandidates`. Never
+read `unresolved` as consistent. Compare the intent with each candidate's
+`statement`, then compile again with `conflictReviews`
+(`{requirementId, verdict: "conflict" | "no_conflict", note}`). On a conflict
+the plan is `blocked`: ask the human which rule holds (a firm requirement is
+theirs), then supersede or change it, or change the intent.
+
 ## Semantic and proof guardrails
 
 Prolog proves only encoded facts. Keep ambiguity, ontology gaps, incomplete

package/dist/traceability/staged-diagnostics.d.ts

@@ -1,6 +1,6 @@
 import type { QualityDiagnostic } from "../public/impact/types.js";
 import { type KibiImpactEvidence } from "./evidence-model.js";
-export type KibiImpactDiagnosticId = "kibi_impact_evidence_missing" | "symbols_manifest_stale" | "symbol_granularity_violation" | "symbol_semantic_review_needed" | "source_file_unowned" | "multi_requirement_symbol_review" | "duplicate_symbol_coordinate_review" | "component_mixed_purpose_review" | "broad_requirement_review" | "requirement_status_review" | "strict_fact_modeling_review" | "logical_coverage_review" | "kibi_impact_override_missing_rationale" | "entity_id_style_review";
+export type KibiImpactDiagnosticId = "kibi_impact_evidence_missing" | "symbols_manifest_stale" | "symbol_granularity_violation" | "symbol_semantic_review_needed" | "source_file_unowned" | "requirement_statement_unverified" | "multi_requirement_symbol_review" | "duplicate_symbol_coordinate_review" | "component_mixed_purpose_review" | "broad_requirement_review" | "requirement_status_review" | "strict_fact_modeling_review" | "logical_coverage_review" | "kibi_impact_override_missing_rationale" | "entity_id_style_review";
 export interface KibiImpactDiagnostic extends QualityDiagnostic {
     /** Stable staged-enforcement diagnostic identifier. */
     id: KibiImpactDiagnosticId;

package/dist/traceability/staged-diagnostics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"staged-diagnostics.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-diagnostics.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAGL,KAAK,kBAAkB,EAKxB,MAAM,qBAAqB,CAAC;AAQ7B,MAAM,MAAM,sBAAsB,GAC9B,8BAA8B,GAC9B,wBAAwB,GACxB,8BAA8B,GAC9B,+BAA+B,GAC/B,qBAAqB,GACrB,iCAAiC,GACjC,oCAAoC,GACpC,gCAAgC,GAChC,0BAA0B,GAC1B,2BAA2B,GAC3B,6BAA6B,GAC7B,yBAAyB,GACzB,wCAAwC,GACxC,wBAAwB,CAAC;AAE7B,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D,uDAAuD;IACvD,EAAE,EAAE,sBAAsB,CAAC;IAC3B,QAAQ,EAAE,iBAAiB,CAAC,UAAU,CAAC,CAAC;IACxC,iEAAiE;IACjE,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,gDAAgD;IAChD,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAsID,wBAAgB,wCAAwC,CACtD,QAAQ,EAAE,kBAAkB,GAC3B,oBAAoB,CAoBtB;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,kBAAkB,EAC5B,mBAAmB,GAAE,MAAmC,GACvD,oBAAoB,EAAE,CAiDxB"}
+{"version":3,"file":"staged-diagnostics.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-diagnostics.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAGL,KAAK,kBAAkB,EAKxB,MAAM,qBAAqB,CAAC;AAQ7B,MAAM,MAAM,sBAAsB,GAC9B,8BAA8B,GAC9B,wBAAwB,GACxB,8BAA8B,GAC9B,+BAA+B,GAC/B,qBAAqB,GACrB,kCAAkC,GAClC,iCAAiC,GACjC,oCAAoC,GACpC,gCAAgC,GAChC,0BAA0B,GAC1B,2BAA2B,GAC3B,6BAA6B,GAC7B,yBAAyB,GACzB,wCAAwC,GACxC,wBAAwB,CAAC;AAE7B,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D,uDAAuD;IACvD,EAAE,EAAE,sBAAsB,CAAC;IAC3B,QAAQ,EAAE,iBAAiB,CAAC,UAAU,CAAC,CAAC;IACxC,iEAAiE;IACjE,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,gDAAgD;IAChD,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAsID,wBAAgB,wCAAwC,CACtD,QAAQ,EAAE,kBAAkB,GAC3B,oBAAoB,CAoBtB;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,kBAAkB,EAC5B,mBAAmB,GAAE,MAAmC,GACvD,oBAAoB,EAAE,CAiDxB"}

package/dist/utils/config.d.ts

@@ -35,6 +35,14 @@ export interface LegacyKbConfig {
     checks?: unknown;
     defaultBranch?: string;
 }
+/**
+ * The first step on a workspace with a legacy `.kb/config.json` and no
+ * manifest. Doctor and kb_status both name it, so they never disagree on
+ * what to run first: `kibi init` would claim the latest schema and skip the
+ * legacy migration steps.
+ */
+export declare const LEGACY_KB_MIGRATION_COMMAND = "kibi migrate --yes";
+export declare const LEGACY_KB_MIGRATION_NOTE = "it creates the manifest from the legacy .kb/config.json; do not run kibi init first";
 /** Whether a legacy `.kb/config.json` exists at the workspace root. */
 export declare function legacyConfigExists(cwd: string): boolean;
 /**

package/dist/utils/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/utils/config.ts"],"names":[],"mappings":"AAoBA,OAAO,EAEL,KAAK,aAAa,EAEnB,MAAM,eAAe,CAAC;AAEvB;;;;;;GAMG;AAEH,YAAY,EAAE,aAAa,EAAE,CAAC;AAE9B,6EAA6E;AAC7E,eAAO,MAAM,oBAAoB,EAAE,aAAsC,CAAC;AAE1E;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,GAAE,MAAsB,GAAG,aAAa,CAE3E;AAED,6EAA6E;AAC7E,MAAM,WAAW,mBAAmB;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,mBAAmB,CAAC;IAC5B,wDAAwD;IACxD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,uBAAuB,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,gBAAgB,CAAC;IACrE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAcD,uEAAuE;AACvE,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,GAET;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,cAAc,CAAA;CAAE,CAqE9C;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,cAAc,GAAG,SAAS,GACjC,aAAa,CAwBf"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/utils/config.ts"],"names":[],"mappings":"AAoBA,OAAO,EAEL,KAAK,aAAa,EAEnB,MAAM,eAAe,CAAC;AAEvB;;;;;;GAMG;AAEH,YAAY,EAAE,aAAa,EAAE,CAAC;AAE9B,6EAA6E;AAC7E,eAAO,MAAM,oBAAoB,EAAE,aAAsC,CAAC;AAE1E;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,GAAE,MAAsB,GAAG,aAAa,CAE3E;AAED,6EAA6E;AAC7E,MAAM,WAAW,mBAAmB;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,mBAAmB,CAAC;IAC5B,wDAAwD;IACxD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,uBAAuB,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,gBAAgB,CAAC;IACrE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAcD;;;;;GAKG;AAEH,eAAO,MAAM,2BAA2B,uBAAuB,CAAC;AAEhE,eAAO,MAAM,wBAAwB,wFACkD,CAAC;AAExF,uEAAuE;AACvE,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,GAET;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,cAAc,CAAA;CAAE,CAqE9C;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,cAAc,GAAG,SAAS,GACjC,aAAa,CAwBf"}

package/dist/utils/config.js

@@ -34,6 +34,16 @@ function pickLegacyPathValue(paths, key) {
     const value = paths[key];
     return typeof value === "string" ? value : undefined;
 }
+/**
+ * The first step on a workspace with a legacy `.kb/config.json` and no
+ * manifest. Doctor and kb_status both name it, so they never disagree on
+ * what to run first: `kibi init` would claim the latest schema and skip the
+ * legacy migration steps.
+ */
+// implements REQ-legacy-kb-first-step-migrate
+export const LEGACY_KB_MIGRATION_COMMAND = "kibi migrate --yes";
+// implements REQ-legacy-kb-first-step-migrate
+export const LEGACY_KB_MIGRATION_NOTE = "it creates the manifest from the legacy .kb/config.json; do not run kibi init first";
 /** Whether a legacy `.kb/config.json` exists at the workspace root. */
 export function legacyConfigExists(cwd) {
     return existsSync(path.join(cwd, ".kb", "config.json"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cli",
-  "version": "2.26.3",
+  "version": "2.27.0",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {
@@ -235,7 +235,7 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-core": "^0.22.2",
+    "kibi-core": "^0.22.3",
     "kibi-plugin-builtin": "^0.5.2",
     "kibi-plugin-sdk": "^0.5.0",
     "kibi-swipl": "^1.0.1",

package/src/public/impact/analyzer.ts

@@ -20,6 +20,11 @@ import {
   createImpactManifestLookup,
   readImpactManifestResults,
 } from "./manifest.js";
+import {
+  createRequirementStatementDiagnostics,
+  readWorkspaceRequirement,
+  workspaceFileChanged,
+} from "./requirement-statements.js";
 import { normalizeSourceFile } from "./source-changes.js";
 import { collectSourceChanges, uniqueSorted } from "./source-changes.js";
 import {
@@ -34,6 +39,14 @@ import type {
 } from "./types.js";
 import { createUnownedFileDiagnostics } from "./unowned-files.js";
 
+/** The workspace-relative document a requirement was read from. */
+function requirementSourcePath(requirement: { id: string; source: string }) {
+  const source = requirement.source;
+  return source && !source.includes("://")
+    ? source.replace(/^\.\//, "")
+    : `.kb/requirements/${requirement.id}.md`;
+}
+
 export async function analyzeChangedFileImpact(
   options: ChangedFileImpactOptions,
 ): Promise<ChangedFileImpactResult> {
@@ -88,12 +101,15 @@ export async function analyzeChangedFileImpact(
           .map((file) => file.path)
       : sourceChanges.map((change) => change.file),
   );
-  const manifestResults = snapshot
+  const snapshotKnowledge = snapshot
     ? readSnapshotKnowledge(
         snapshot.readGit,
         snapshot.headTree,
         snapshot.readBlobs,
-      ).filter((result) => result.entity.type === "symbol")
+      )
+    : undefined;
+  const manifestResults = snapshotKnowledge
+    ? snapshotKnowledge.filter((result) => result.entity.type === "symbol")
     : readImpactManifestResults(workspaceRoot);
   const manifestLookup = createImpactManifestLookup(manifestResults);
   const symbolsByFile = new Map<string, ExtractedSymbol[]>();
@@ -161,6 +177,26 @@ export async function analyzeChangedFileImpact(
             requestedFiles: [...filter],
             linkedSourceFiles,
           }),
+          // What the changed code is meant to do, quoted, before the
+          // structural findings: "no violations" never compared it.
+          ...createRequirementStatementDiagnostics({
+            workspaceRoot,
+            symbolsByFile,
+            readRequirement: (id) =>
+              snapshotKnowledge
+                ? snapshotKnowledge.find((result) => result.entity.id === id)
+                    ?.entity
+                : readWorkspaceRequirement(workspaceRoot, id),
+            requirementChanged: (requirement) =>
+              snapshot
+                ? snapshot.inventory.some(
+                    (file) => file.path === requirementSourcePath(requirement),
+                  )
+                : workspaceFileChanged(
+                    workspaceRoot,
+                    requirementSourcePath(requirement),
+                  ),
+          }),
           ...createSymbolGranularityDiagnostics({
             manifestResults: activeManifestResults,
             symbolsByFile,

package/src/public/impact/requirement-statements.ts

@@ -0,0 +1,171 @@
+import { execFileSync } from "node:child_process";
+import * as path from "node:path";
+import { effectiveFirmness } from "../../decision-firmness.js";
+import {
+  type ExtractedEntity,
+  extractFromMarkdown,
+} from "../../extractors/markdown.js";
+import type { KibiImpactDiagnostic } from "../../traceability/staged-diagnostics.js";
+import type { ExtractedSymbol } from "../../traceability/symbol-extract.js";
+
+/**
+ * Kibi's checks compare structure (links, coverage, facts), never code with a
+ * requirement's prose. A change to code that implements a requirement can
+ * contradict it and still pass every rule, so the check says which
+ * requirements the changed code implements and quotes what each one says,
+ * instead of letting "no violations" read as "the change keeps them".
+ */
+
+const MAX_STATEMENT = 400;
+const MAX_NAMED_SYMBOLS = 4;
+const RETIRED_STATUS =
+  /supersed|deprecat|reject|obsolete|retired|archived|removed|closed/i;
+
+// implements REQ-kb-check-unverified-requirement-statements
+export type RequirementStatementDiagnosticsOptions = {
+  readonly workspaceRoot: string;
+  readonly symbolsByFile: ReadonlyMap<string, readonly ExtractedSymbol[]>;
+  /** The requirement entity for an id, or undefined when it is unknown. */
+  readonly readRequirement: (id: string) => ExtractedEntity | undefined;
+  /** Whether the requirement's document changed in this change. */
+  readonly requirementChanged: (requirement: ExtractedEntity) => boolean;
+};
+
+function implementedRequirementIds(symbol: ExtractedSymbol): string[] {
+  return [
+    ...(symbol.relationships ?? [])
+      .filter((relationship) => relationship.type === "implements")
+      .map((relationship) => relationship.to),
+    ...symbol.reqLinks,
+  ].filter((id) => id.startsWith("REQ-"));
+}
+
+function truncate(text: string, limit: number): string {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > limit ? `${flat.slice(0, limit - 1)}…` : flat;
+}
+
+// implements REQ-kb-check-unverified-requirement-statements
+/**
+ * One `requirement_statement_unverified` warning per current requirement that
+ * a changed behavioral symbol implements, quoting the requirement's statement
+ * and firmness. A requirement whose own document changed in the same change
+ * is left to the firmness and supersede checks.
+ */
+export function createRequirementStatementDiagnostics(
+  options: RequirementStatementDiagnosticsOptions,
+): KibiImpactDiagnostic[] {
+  const symbolsByRequirement = new Map<
+    string,
+    { names: Set<string>; files: Set<string> }
+  >();
+  for (const symbols of options.symbolsByFile.values()) {
+    for (const symbol of symbols) {
+      if (symbol.role !== "behavioral" || symbol.hunkRanges.length === 0)
+        continue;
+      for (const id of implementedRequirementIds(symbol)) {
+        const entry = symbolsByRequirement.get(id) ?? {
+          names: new Set<string>(),
+          files: new Set<string>(),
+        };
+        entry.names.add(symbol.name);
+        entry.files.add(symbol.location.file);
+        symbolsByRequirement.set(id, entry);
+      }
+    }
+  }
+
+  const diagnostics: KibiImpactDiagnostic[] = [];
+  for (const id of [...symbolsByRequirement.keys()].sort()) {
+    const requirement = options.readRequirement(id);
+    if (requirement === undefined || requirement.type !== "req") continue;
+    if (RETIRED_STATUS.test(requirement.status ?? "")) continue;
+    if (options.requirementChanged(requirement)) continue;
+    const entry = symbolsByRequirement.get(id);
+    if (entry === undefined) continue;
+    const firmness = effectiveFirmness(
+      "req",
+      requirement.firmness,
+      requirement.origin,
+    );
+    const label =
+      firmness === "firm"
+        ? "firm: ask before changing"
+        : (firmness ?? "default");
+    const statement = truncate(
+      requirement.semantic_text ?? requirement.title,
+      MAX_STATEMENT,
+    );
+    const sorted = [...entry.names].sort();
+    const names =
+      sorted.length > MAX_NAMED_SYMBOLS
+        ? `${sorted.slice(0, MAX_NAMED_SYMBOLS).join(", ")} and ${sorted.length - MAX_NAMED_SYMBOLS} more`
+        : sorted.join(", ");
+    const verb = sorted.length === 1 ? "implements" : "implement";
+    diagnostics.push({
+      id: "requirement_statement_unverified",
+      severity: "warning",
+      blocking: false,
+      category: "requirement",
+      entityId: id,
+      files: [...entry.files].sort(),
+      docs: ["docs/symbol-traceability-taxonomy.md"],
+      message: `The change edits ${names}, which ${verb} ${id} [${label}]: "${statement}" Kibi compared links and facts, not the code with this statement, so no violation here does not mean the change keeps it.`,
+      suggestion:
+        firmness === "firm"
+          ? `Confirm the changed code still does what ${id} says. If it no longer does, the request conflicts with a rule a person set: stop and ask whether to change ${id}; change it only with their words in origin.ref, and say in the final answer which rule changed.`
+          : `Confirm the changed code still does what ${id} says. If it no longer does, the request conflicts with a recorded rule: ask whether to change ${id} before keeping the change, then supersede or update it in the same change with the person's words, and say in the final answer which rule changed.`,
+      evidence: {
+        requirement: id,
+        firmness: firmness ?? "default",
+        statement,
+        symbols: sorted,
+      },
+    });
+  }
+  return diagnostics;
+}
+
+// implements REQ-kb-check-unverified-requirement-statements
+/**
+ * Whether Git reports any change (staged, unstaged or untracked) to a
+ * workspace file against HEAD. Outside a repository nothing counts as changed.
+ */
+export function workspaceFileChanged(
+  workspaceRoot: string,
+  relativePath: string,
+): boolean {
+  try {
+    const output = execFileSync(
+      "git",
+      ["status", "--porcelain", "--", relativePath],
+      {
+        cwd: workspaceRoot,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      },
+    );
+    return output.trim() !== "";
+  } catch {
+    return false;
+  }
+}
+
+// implements REQ-kb-check-unverified-requirement-statements
+/**
+ * Read a requirement from its canonical document in the working tree
+ * (`.kb/requirements/<id>.md`).
+ */
+export function readWorkspaceRequirement(
+  workspaceRoot: string,
+  id: string,
+): ExtractedEntity | undefined {
+  if (!/^REQ-[A-Za-z0-9._-]+$/.test(id)) return undefined;
+  try {
+    return extractFromMarkdown(
+      path.join(workspaceRoot, ".kb", "requirements", `${id}.md`),
+    ).entity;
+  } catch {
+    return undefined;
+  }
+}

package/src/public/operations/check-format-shared.ts

@@ -126,10 +126,31 @@ export function formatQualityDiagnosticsText(
   return `${diagnostics.length} quality diagnostic${diagnostics.length === 1 ? "" : "s"} found\n${details.join("\n")}`;
 }
 
-// implements REQ-mcp-tool-check
-export function formatViolationText(violations: readonly Violation[]): string {
+/**
+ * Requirements the changed code implements whose statements the check did not
+ * compare with the code (`requirement_statement_unverified`).
+ */
+// implements REQ-kb-check-unverified-requirement-statements
+function unverifiedRequirementIds(input: {
+  readonly impactResult: ChangedFileImpactResult | undefined;
+}): string[] {
+  return (input.impactResult?.impactDiagnostics ?? [])
+    .filter(
+      (diagnostic) => diagnostic.id === "requirement_statement_unverified",
+    )
+    .map((diagnostic) => diagnostic.entityId)
+    .filter((id): id is string => id !== undefined);
+}
+
+// implements REQ-mcp-tool-check, REQ-kb-check-unverified-requirement-statements
+export function formatViolationText(
+  violations: readonly Violation[],
+  unverifiedRequirements: readonly string[] = [],
+): string {
   if (violations.length === 0) {
-    return "No violations found";
+    return unverifiedRequirements.length === 0
+      ? "No violations found"
+      : `No structural violations found. The changed code implements ${unverifiedRequirements.join(", ")}; Kibi did not compare the code with ${unverifiedRequirements.length === 1 ? "its statement" : "their statements"} (quoted under requirement_statement_unverified below), so confirm the change still does what each says, and ask the person before keeping a change that contradicts one`;
   }
 
   const details = violations.map((violation) => {
@@ -205,7 +226,9 @@ export function buildSummary(input: {
   readonly impactResult: ChangedFileImpactResult | undefined;
   readonly qualityDiagnostics: readonly QualityDiagnostic[];
 }): string {
-  const sections = [formatViolationText(input.violations)];
+  const sections = [
+    formatViolationText(input.violations, unverifiedRequirementIds(input)),
+  ];
   if (input.evaluated !== undefined)
     sections.push(formatEvaluatedText(input.evaluated));
   if (input.impactResult !== undefined) {

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

@@ -1359,36 +1359,43 @@ export async function executeStatus(
           bootstrapActivation.activationState === "root_active_thin" &&
           !bootstrapActivation.applyBlocked,
         reason: bootstrapActivation.reason,
+        // implements REQ-legacy-kb-first-step-migrate
         nextAction:
-          bootstrapActivation.activationState === "root_uninitialized"
+          bootstrapActivation.nextOperation !== undefined
             ? {
-                operation: "kibi init",
+                operation: bootstrapActivation.nextOperation,
                 reason: bootstrapActivation.reason,
                 required: true,
               }
-            : bootstrapActivation.activationState === "root_partial"
+            : bootstrapActivation.activationState === "root_uninitialized"
               ? {
-                  operation: "kibi doctor",
+                  operation: "kibi init",
                   reason: bootstrapActivation.reason,
                   required: true,
                 }
-              : bootstrapActivation.activationState === "vendored_only"
+              : bootstrapActivation.activationState === "root_partial"
                 ? {
-                    operation: "move-to-project-root",
+                    operation: "kibi doctor",
                     reason: bootstrapActivation.reason,
                     required: true,
                   }
-                : bootstrapActivation.activationState === "root_active_thin"
+                : bootstrapActivation.activationState === "vendored_only"
                   ? {
-                      operation: "kb_plan_bootstrap",
+                      operation: "move-to-project-root",
                       reason: bootstrapActivation.reason,
                       required: true,
                     }
-                  : {
-                      operation: "continue-kibi-workflow",
-                      reason: bootstrapActivation.reason,
-                      required: false,
-                    },
+                  : bootstrapActivation.activationState === "root_active_thin"
+                    ? {
+                        operation: "kb_plan_bootstrap",
+                        reason: bootstrapActivation.reason,
+                        required: true,
+                      }
+                    : {
+                        operation: "continue-kibi-workflow",
+                        reason: bootstrapActivation.reason,
+                        required: false,
+                      },
       },
     };
     return {

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

@@ -344,6 +344,16 @@ export function digestMigrationPlan(plan: MigrationPlan): MigrationPlanDigest {
       });
     else group.count += 1;
   }
+  const automaticActions = plan.actions.filter(
+    (action) => action.safety === "automatic",
+  );
+  const blockedAutomatic = automaticActions.filter(
+    (action) => action.state === "blocked",
+  ).length;
+  const blockedNote =
+    blockedAutomatic === 0
+      ? ""
+      : ` ${blockedAutomatic === 1 ? "1 automatic action is" : `${blockedAutomatic} automatic actions are`} blocked: it waits for the actions in its dependsOn and needs no approval until a later plan shows it ready.`;
   return {
     version: MIGRATION_PLAN_DIGEST_VERSION,
     planHash: plan.planHash,
@@ -351,9 +361,7 @@ export function digestMigrationPlan(plan: MigrationPlan): MigrationPlanDigest {
     expected: plan.expected,
     scope: plan.scope,
     summary: plan.summary,
-    automaticActions: plan.actions.filter(
-      (action) => action.safety === "automatic",
-    ),
+    automaticActions,
     actionGroups: [...groups.values()].sort(
       (left, right) =>
         right.count - left.count ||
@@ -361,7 +369,7 @@ export function digestMigrationPlan(plan: MigrationPlan): MigrationPlanDigest {
         left.state.localeCompare(right.state),
     ),
     diagnostics: plan.diagnostics,
-    next: "This digest cannot be applied. Run kb_status, kb_check and kb_coverage (or kibi migrate) for the full plan and its action details.",
+    next: `This digest cannot be applied. Run kb_status, kb_check and kb_coverage (or kibi migrate) for the full plan and its action details.${blockedNote}`,
   };
 }
 

package/src/public/operations/result-envelope.ts

@@ -166,6 +166,9 @@ function extraFailedEffects(
   });
 }
 
+/** The envelope error code of a kb_upsert dry run on an invalid payload. */
+export const UPSERT_DRY_RUN_INVALID = "UPSERT_DRY_RUN_INVALID" as const;
+
 export function resultVersion(spec: {
   readonly name: OperationName | string;
   readonly resultVersion?: string;
@@ -207,15 +210,26 @@ export function toKibiResult<T>(
   const migrationRefused =
     row?.version === "kibi.migration-apply-result.v1" &&
     row.outcome === "refused";
+  // implements REQ-kibi-symbol-link-guidance
+  // A kb_upsert dry run that finds the payload invalid reports what the
+  // write would do: refuse it. Its data still carries the errors.
+  const dryRunInvalid = row?.dryRun === true && row.valid === false;
   let status = options.status;
   if (!status) {
     status = "success";
     if (row?.status === "committed_with_repairs")
       status = "committed_with_repairs";
-    if (row?.status === "rejected" || migrationRefused) status = "error";
+    if (row?.status === "rejected" || migrationRefused || dryRunInvalid)
+      status = "error";
   }
-  const terminalError =
-    row?.status === "rejected"
+  const terminalError = dryRunInvalid
+    ? {
+        code: UPSERT_DRY_RUN_INVALID,
+        message:
+          `Dry run: kb_upsert would refuse this payload; nothing was written. ${Array.isArray(row.errors) ? row.errors.map(String).join("; ") : ""}`.trim(),
+        retryable: false,
+      }
+    : row?.status === "rejected"
       ? {
           code: "BOOTSTRAP_PLAN_REJECTED",
           message:
@@ -233,7 +247,7 @@ export function toKibiResult<T>(
   const resultError = options.error ?? terminalError;
   const outcome = effectOutcome(
     status,
-    migrationRefused && options.attempted === undefined
+    (migrationRefused || dryRunInvalid) && options.attempted === undefined
       ? { ...options, attempted: false }
       : options,
   );

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

@@ -40,7 +40,7 @@ export const checkSpec = {
       includeImpactDiagnostics: {
         type: "boolean",
         description:
-          "When true, include changed-file impact diagnostics such as symbol_granularity_violation, symbol_semantic_review_needed and source_file_unowned in structured output.",
+          "When true, include changed-file impact diagnostics such as symbol_granularity_violation, symbol_semantic_review_needed, source_file_unowned and requirement_statement_unverified (each current requirement the changed code implements, with its statement and firmness, since the check never compares code with a statement) in structured output.",
       },
       maxDiagnostics: {
         type: "integer",

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

@@ -35,7 +35,7 @@ export const compileIntentSpec = {
   name: "kb_compile_intent",
   cliName: "compile-intent",
   description:
-    "Compile complete change intent into a deterministic, snapshot-bound read-only plan. Reuses intent-aware discovery and semantic modeling, accounts for every proposition, reports contradiction witnesses, proposes traceability links, and emits dependency-ordered kb_upsert-style steps only for resolved typed claims. No mutation side effects.",
+    "Compile complete change intent into a deterministic, snapshot-bound read-only plan. Reuses intent-aware discovery and semantic modeling, accounts for every proposition, reports contradiction witnesses, proposes traceability links, and emits dependency-ordered kb_upsert-style steps only for resolved typed claims. contradictionAnalysis.outcome is no_conflict only when the check could decide: an unmodeled proposition or a related current requirement without logic leaves it unresolved with reasons and reviewCandidates to compare and judge through conflictReviews. No mutation side effects.",
   businessInputSchema: {
     type: "object",
     required: ["intent", "mode"],
@@ -198,6 +198,22 @@ export const compileIntentSpec = {
         description:
           "Explicit decisions for deterministic traceability proposals. Pending proposals never enter steps.",
       },
+      conflictReviews: {
+        type: "array",
+        maxItems: 20,
+        items: {
+          type: "object",
+          required: ["requirementId", "verdict"],
+          additionalProperties: false,
+          properties: {
+            requirementId: { type: "string", minLength: 1 },
+            verdict: { type: "string", enum: ["conflict", "no_conflict"] },
+            note: { type: "string", maxLength: 2000 },
+          },
+        },
+        description:
+          "Your verdict on each contradictionAnalysis.reviewCandidates entry of a previous compile: whether the intent contradicts that current requirement, which Kibi could not compare logically. A conflict verdict blocks the plan; a no_conflict verdict clears that candidate. A verdict may also name a current requirement discovery did not rank.",
+      },
     },
   },
   requiresProlog: true,

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.14.0
+version: 3.15.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -37,7 +37,7 @@ Seed branch-local Kibi knowledge from cited product intent, without creating a p
 3. **Declare** `bootstrapContext`: `projectSummary`; `knowledgeSources` (id, kind, title, locator, authority, optional connector, optional `component`); `intentClaims` (statement, sourceId, reference, `excerpt` required for `intent` and `observation` claims and optional for `open_question`, optional `kind`, default `intent`, optional `component` overriding the source's, optional `rationale` with the reason the source or the human gave, never invented); `conflicts` (`claimReferences` naming two or more declared claims by sourceId and reference, plus a one-sentence `note`). Only intent claims can become requirements, and they are recorded as the people's rules: `origin.kind: import` with `sourceId:reference` as `origin.ref`, and `firmness: firm`, so a later agent asks before changing one (normative lines from repository Markdown get the same, citing `path#Lline`). Observations, open questions (tagged `review:open-question`) and conflicts (tagged `review:conflict`) become cited observation facts. Generated subject keys take the shape `component.aspect`: name the component each source or claim is about (for example `recorder`; set `component` on the knowledge source, or on a claim to override it; repository Markdown takes its file or directory name), because an intent claim whose subject is neither one word nor already dotted, with no component, is reported in the plan diagnostics and left as an authoring follow-up instead of a malformed key. The aspect is the claim's subject, or its constrained property when the subject is the component itself. An aspect over four words or 40 characters is shortened to a noun phrase (words before `when`, `while`, `for`, `and`, ...; `support_inbox.update_in_real_time_when_a_new_ticket_is_assigned...` becomes `support_inbox.update_in_real_time`) and reported as `subject-key-shortened:` with both keys; two different subjects that shorten alike get a third segment (`editor.discard_a_draft.leaving`) and a `subject-key-disambiguated:` diagnostic; claims about one subject share one subject fact, and a `subject-key-shared:` diagnostic names the key and its sources. Show these diagnostics to the human with the plan so they can rename a key before approval. Kibi never contacts these sources. It binds your declaration into the plan hash.
 4. **Preview** with `kb_plan_bootstrap` (or `plan-bootstrap --input`), read-only. On `needs_context`, ask only its bounded questions (four at most), then preview again. When `pluginOffers` is non-empty (for example `kibi-plugin-ui` because UI component files exist), ask the human once whether to enable each offered plugin, naming its evidence files. On yes, install it as a dev dependency and add it to `package.json` `kibi.plugins` with the offered capability in `augment` mode; on no, add its name to `kibi.declinedPlugins` so it is not offered again. Either way the human decides; never enable a plugin unasked. For `kibi-plugin-ui`, step 11 also captures the UI pattern inventory (see `kibi-usage` `resources/ui-requirements.md`).
 5. **Narrow with filters, not caps.** Read the `tldr` and the `Suppressed candidates by reason` diagnostic before individual rows. If the output is too large or mostly tooling or metadata, re-preview with `entityTypes` or declared `sourceOfTruthPaths`. Generic Markdown is off by default once you declare intent claims; set `includeGenericMarkdown: true` only for repository docs the human named. Keep confirmed intent claims: they are never capped and never use `maxCandidates`, which is the separate budget for candidates Kibi discovers (symbols, tests, repository docs). Raise it only when discovered candidates you need are `over_limit`, and never for provenance stubs: a provider entry with no claim (`Source module: …`, repository metadata, layout roots) is planned last as a `meta` fact tagged `bootstrap:provenance-stub`, `discoverySummary.provenanceStubs` counts them apart from `candidatesWithClaims`, and the `over_limit` diagnostic says how many suppressed candidates are stubs; they add no knowledge, so a plan that is mostly stubs needs `entityTypes` or declared sources, not a higher cap. Read the per-source `Knowledge source …` diagnostics: each splits the claims not planned by reason (suppressed by the activation mode, a `suppressedCandidates` row, a `sourceOnlySignals` follow-up). Report them per source and restate them before approval, or carry them to step 11 with their citation.
-6. **Request approval.** Show the complete `structuredContent.plan`, the full hash (never abbreviated), which candidates cite which sources, what was omitted, the open questions and declared conflicts it records for the human to decide, and any claim that contradicts code. If you find an undeclared contradiction now, add it to `conflicts` and preview again rather than resolving it. With no answer, stop as "awaiting approval." If declined, replan and ask again with the new hash.
+6. **Request approval.** Show the complete `structuredContent.plan`, the full hash (never abbreviated), which candidates cite which sources, what was omitted, the open questions and declared conflicts it records for the human to decide, and any claim that contradicts code. If you find an undeclared contradiction now, add it to `conflicts` and preview again rather than resolving it. A `conflict-review:` diagnostic (and `review_against:<id>` evidence on the candidate) names current requirements Kibi could not check a planned claim against because they have no logic: compare each pair yourself and show any contradiction to the human with the plan; they decide whether to drop the claim or keep it and supersede the requirement after apply. With no answer, stop as "awaiting approval." If declined, replan and ask again with the new hash.
 7. **Pre-apply check.** The plan you send must equal the returned plan: every top-level field, including `suppressedCandidates`, `diagnostics`, `candidates`, `actions`, and `expected`, with every array the same length and order. Never rebuild it from preview fields. If the host cannot pass the exact object, stop and say so.
 8. **Apply once** with `kb_apply_plan`, the exact plan, and `approvedPlanHash`. The operation owns dependency ordering, source-first writes, sequential mutation, and recovery journaling. A plan with hundreds of actions can run for minutes: pass a `progressToken` (Kibi sends progress after each action) with a client that resets its timeout on progress, or pass `async: true` and poll `kb_job_status` when the host has it. If the apply is cut off, call `kb_apply_plan` with only the `recoveryJournalId` from `kb_status` or the error; it resumes an action interrupted mid-write and reclaims a lock left by a dead process. Never edit or delete `.kb/recovery` files; if recovery is refused, stop and report it.
 9. **Read back** with `kb_query` and `kb_search` to confirm writes and citations.

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.19.0
+version: 2.20.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -410,6 +410,16 @@ Conditional clauses ("only when", "only if", "must not ... unless") compile
 into typed `forbid` rules linked by `requires_rule`, not property facts; one
 `kb_model` or `kb_compile_intent` cannot translate stays an `ontology_gap`.
 
+`kb_compile_intent` reports `contradictionAnalysis.outcome: no_conflict` only
+when it could check: Prolog compares only requirements with logic links. When
+the intent is unmodeled or a related current requirement is prose only, the
+outcome is `unresolved` with `reasons` and up to five `reviewCandidates`. Never
+read `unresolved` as consistent. Compare the intent with each candidate's
+`statement`, then compile again with `conflictReviews`
+(`{requirementId, verdict: "conflict" | "no_conflict", note}`). On a conflict
+the plan is `blocked`: ask the human which rule holds (a firm requirement is
+theirs), then supersede or change it, or change the intent.
+
 ## Semantic and proof guardrails
 
 Prolog proves only encoded facts. Keep ambiguity, ontology gaps, incomplete