kibi-cli 2.14.0 → 2.15.0

package/dist/public/skills/kibi-usage/resources/ui-requirements.md

@@ -1,7 +1,10 @@
 # UI / Visual Requirement Modeling
 
 Optional, per-project lane for recording what the screen should look like so UI edits cannot
-silently drift from the spec. Non-UI projects skip it entirely; no check rule requires it.
+silently drift from the spec. Non-UI projects skip it entirely. Without the experimental
+`kibi-plugin-ui` no check rule requires it; with that plugin active, `kb_check` blocks
+components that lack a design requirement (`policy-ownership`) and implementations that
+lose their pattern markers (`policy-markers`).
 
 ## Three layers
 
@@ -13,12 +16,48 @@ silently drift from the spec. Non-UI projects skip it entirely; no check rule re
    from two current requirements are rejected on write unless `supersedes`.
 3. **Relational predicates** — ground `fact_kind: predicate` linked with `requires_predicate`.
    The built-in `visual_layout_rule(subject, relation, target)` covers "X must remain visually
-   aligned with Y" (relation `aligned_with`). Other relational layout claims need a
-   project-local `predicate_schema` when the task authorizes ontology extension.
+   aligned with Y" (relation `aligned_with`); `ui_pattern`, `same_pattern` and
+   `pattern_marker` cover patterns (below); `ui_container(subject, size, overflow)` covers
+   "a half-page panel that scrolls". Other relational layout claims need a project-local
+   `predicate_schema` when the task authorizes ontology extension.
 
 Kibi enforces stated facts and links, not pixels. Freeform spatial prose is stored and
 searchable but is not machine-checked.
 
+## Patterns and variants
+
+Name the visual pattern a concept uses, and which variants must share it, so a rewrite to a
+different pattern (a line-and-dots timeline redone as cards) is a visible contradiction
+instead of a silent drift. All three predicates are built in:
+
+- `ui_pattern(subject, pattern)`: `ui_pattern(activity_feed, line_dots_timeline)`.
+- `same_pattern(subject, variant, other_variant)`: `same_pattern(activity_feed, editor_view, read_only_view)`.
+- `pattern_marker(pattern, marker)`: `pattern_marker(line_dots_timeline, timeline_dot)`; the
+  marker is a literal class name or test id every implementation of the pattern contains.
+
+Link the first two from the requirement with `requires_predicate`. Marker facts belong to
+the pattern, not to one requirement, so link them from the requirement that introduced the
+pattern or leave them standalone. With `kibi-plugin-ui` active, every component that
+implements a requirement naming a `ui_pattern` must contain each marker of that pattern in
+its source or its `.html` template. A component with no design constraint (a
+layout-free wrapper) carries the tag `review:ui-unconstrained` instead of a requirement.
+
+A requirement grounded only in `ui_pattern`, `same_pattern` and `pattern_marker` is proved
+by component tests: a test with `verification_scope: unit` or `integration` and a fresh
+passing receipt satisfies its scenarios. Write one component test per variant named in
+`same_pattern`; that is what catches a divergent branch inside one template, which the
+static marker check cannot see. Adding any other fact (`ui_container`, a property) brings
+back the end-to-end requirement.
+
+### Capturing the inventory
+
+When the plugin is first enabled on an existing UI, list the patterns the code already
+uses per screen, ask the human which is intended wherever two variants of one concept
+differ, and record each answer as a requirement. Record a divergence the human has not
+decided as an `observation` fact tagged `review:ui-divergence`, citing both files, rather
+than guessing which variant is right. Colours, spacing and component-library choices
+(which scrollbar component to use) belong in a linter, not here.
+
 ## Button position
 
 ```yaml

package/dist/report/html-report.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"html-report.d.ts","sourceRoot":"","sources":["../../src/report/html-report.ts"],"names":[],"mappings":"AAUA,OAAO,EACL,KAAK,YAAY,EAGlB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,KAAK,gBAAgB,EAMtB,MAAM,iBAAiB,CAAC;AAGzB,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAuB9D,eAAO,MAAM,UAAU,6FACqE,CAAC;AAG7F,eAAO,MAAM,wBAAwB,gEAC0B,CAAC;AAEhE,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,OAAO,EAAE,aAAa,CAAC;IACvB,IAAI,EAAE,SAAS,aAAa,EAAE,CAAC;IAC/B,IAAI,CAAC,EAAE,aAAa,CAAC;CACtB,CAAC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,YAAY,EAAE,kBAAkB,CAAC;IACjC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,IAAI,CAAC;IAClB,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC/B,CAAC,CAAC;AAsMH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,SAAS,YAAY,EAAE,EAC9B,MAAM,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,OAAO,GACtC,YAAY,GAAG,QAAQ,CAKzB;AAID,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,aAAa,GAAG,YAAY,GAAG,QAAQ,CAM7E;AA8YD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAuM/D"}
+{"version":3,"file":"html-report.d.ts","sourceRoot":"","sources":["../../src/report/html-report.ts"],"names":[],"mappings":"AAUA,OAAO,EACL,KAAK,YAAY,EAGlB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,KAAK,gBAAgB,EAMtB,MAAM,iBAAiB,CAAC;AAGzB,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAuB9D,eAAO,MAAM,UAAU,6FACqE,CAAC;AAG7F,eAAO,MAAM,wBAAwB,gEAC0B,CAAC;AAEhE,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,OAAO,EAAE,aAAa,CAAC;IACvB,IAAI,EAAE,SAAS,aAAa,EAAE,CAAC;IAC/B,IAAI,CAAC,EAAE,aAAa,CAAC;CACtB,CAAC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,YAAY,EAAE,kBAAkB,CAAC;IACjC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,IAAI,CAAC;IAClB,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC/B,CAAC,CAAC;AAkNH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,SAAS,YAAY,EAAE,EAC9B,MAAM,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,OAAO,GACtC,YAAY,GAAG,QAAQ,CAKzB;AAID,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,aAAa,GAAG,YAAY,GAAG,QAAQ,CAM7E;AA8YD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAuM/D"}

package/dist/report/html-report.js

@@ -117,9 +117,20 @@ function combinedStageState(...statuses) {
 function stagePassed(stages, name) {
     return stageStatus(stages[name]) === "passed";
 }
+/**
+ * A test whose scope its scenario accepts: end-to-end everywhere, plus unit and
+ * integration tests for component-scope UI pattern scenarios. Other tests carry
+ * the `not_end_to_end` state.
+ */
+// implements REQ-ui-pattern-component-proof
+function isProofScopeEvidence(item) {
+    return item.state !== undefined
+        ? item.state !== "not_end_to_end"
+        : item.scope === "end_to_end";
+}
 function hasEndToEndTest(stages) {
     const evidence = records(record(stages.passingE2e).receiptEvidence);
-    return evidence.some((item) => item.scope === "end_to_end");
+    return evidence.some(isProofScopeEvidence);
 }
 function implementationOwned(stages) {
     const productionSymbols = strings(record(stages.productionSymbols).symbols);
@@ -268,7 +279,7 @@ function requirementStages(row, repository) {
     const implementationSymbols = strings(productionSymbols.symbols);
     const missingCoordinates = strings(sourceCoordinatesStage.missingSymbols);
     const receiptEvidence = records(passingE2e.receiptEvidence);
-    const hasE2e = receiptEvidence.some((item) => item.scope === "end_to_end");
+    const hasE2e = receiptEvidence.some(isProofScopeEvidence);
     const factSources = sourceCoordinates(record(stages.logicGrounding).sources);
     const scenarioSources = sourceCoordinates(record(stages.scenarios).sources);
     const testSources = sourceCoordinates(record(stages.scenarioTests).sources);

package/dist/utils/rule-registry.generated.d.ts

@@ -223,5 +223,15 @@ export declare const GENERATED_RULES: readonly [{
     readonly enforcementClass: "advisory";
     readonly category: "lifecycle";
     readonly diagnosticSeverity: "info";
+}, {
+    readonly name: "policy-ownership";
+    readonly description: "When a plugin activated for kibi.check-policy.v1 declares ownership rules, every production symbol in a rule's file set must implement a current requirement grounded (requires_predicate) in one of the rule's predicates; projects without an activated check policy are unaffected";
+    readonly enforcementClass: "canonical";
+    readonly category: "traceability";
+}, {
+    readonly name: "policy-markers";
+    readonly description: "When a plugin activated for kibi.check-policy.v1 declares marker rules, every file implementing a requirement grounded in the rule's pattern predicate (with its declared sibling files) must contain each marker the KB declares for that pattern";
+    readonly enforcementClass: "canonical";
+    readonly category: "traceability";
 }];
 //# sourceMappingURL=rule-registry.generated.d.ts.map

package/dist/utils/rule-registry.generated.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rule-registry.generated.d.ts","sourceRoot":"","sources":["../../src/utils/rule-registry.generated.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuTlB,CAAC"}
+{"version":3,"file":"rule-registry.generated.d.ts","sourceRoot":"","sources":["../../src/utils/rule-registry.generated.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqUlB,CAAC"}

package/dist/utils/rule-registry.generated.js

@@ -277,4 +277,16 @@ export const GENERATED_RULES = [
         category: "lifecycle",
         diagnosticSeverity: "info",
     },
+    {
+        name: "policy-ownership",
+        description: "When a plugin activated for kibi.check-policy.v1 declares ownership rules, every production symbol in a rule's file set must implement a current requirement grounded (requires_predicate) in one of the rule's predicates; projects without an activated check policy are unaffected",
+        enforcementClass: "canonical",
+        category: "traceability",
+    },
+    {
+        name: "policy-markers",
+        description: "When a plugin activated for kibi.check-policy.v1 declares marker rules, every file implementing a requirement grounded in the rule's pattern predicate (with its declared sibling files) must contain each marker the KB declares for that pattern",
+        enforcementClass: "canonical",
+        category: "traceability",
+    },
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cli",
-  "version": "2.14.0",
+  "version": "2.15.0",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {
@@ -235,9 +235,9 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-core": "^0.17.3",
-    "kibi-plugin-builtin": "^0.4.2",
-    "kibi-plugin-sdk": "^0.4.1",
+    "kibi-core": "^0.18.0",
+    "kibi-plugin-builtin": "^0.5.0",
+    "kibi-plugin-sdk": "^0.5.0",
     "kibi-swipl": "^1.0.1",
     "saxes": "^6.0.0",
     "ignore": "^5.3.0",

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

@@ -33,6 +33,7 @@ import {
   resolveCheckRules,
   stagedEntityIdStyleDiagnostics,
 } from "./check-helpers.js";
+import { collectCheckPolicyViolations } from "./check-policy-rules.js";
 import { executeStatus } from "./discovery-executors.js";
 import { collectEntityContextViolations } from "./entity-context.js";
 import {
@@ -229,6 +230,11 @@ export async function executeCheck(
       rulesAllowlist,
       workspaceRoot,
     );
+    const checkPolicyFindings = await collectCheckPolicyViolations(
+      prolog,
+      rulesAllowlist,
+      workspaceRoot,
+    );
     const partitioned = partitionCheckFindings([
       ...aggregatedFindings,
       ...queryPlanViolations,
@@ -237,6 +243,7 @@ export async function executeCheck(
       ...predicateConformanceFindings,
       ...originReviewFindings,
       ...entityContextFindings,
+      ...checkPolicyFindings,
     ]);
     const violations: Violation[] = partitioned.violations;
 

package/src/public/operations/check-policy-rules.ts

@@ -0,0 +1,462 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+
+import * as fs from "node:fs";
+import {
+  basename,
+  dirname,
+  extname,
+  isAbsolute,
+  join,
+  posix,
+  relative,
+} from "node:path";
+import ignore from "ignore";
+import type {
+  CheckPolicyMarkerRule,
+  CheckPolicyOwnershipRule,
+} from "kibi-plugin-sdk";
+
+import {
+  type ActiveCheckPolicy,
+  type CheckPolicyLoadError,
+  readActiveCheckPolicies,
+} from "../../plugins/check-policies.js";
+import { parseListOfLists, parsePrologValue } from "../../prolog/codec.js";
+import type { Violation } from "../../utils/rule-registry.js";
+import { loadEntitiesPaged } from "./discovery-entities.js";
+import type { PrologPort } from "./runtime-types.js";
+
+/** Symbols in a policy's file set must implement a qualifying requirement. */
+// implements REQ-capability-check-policy
+export const POLICY_OWNERSHIP_RULE = "policy-ownership";
+/** Files implementing a pattern must keep the pattern's declared markers. */
+// implements REQ-capability-check-policy
+export const POLICY_MARKERS_RULE = "policy-markers";
+
+const POLICY_RULES = [POLICY_OWNERSHIP_RULE, POLICY_MARKERS_RULE] as const;
+
+// implements REQ-capability-check-policy
+export type PolicySymbol = Readonly<{
+  id: string;
+  title: string;
+  sourceFile: string;
+  tags: readonly string[];
+}>;
+
+// implements REQ-capability-check-policy
+export type PolicyPredicateFact = Readonly<{
+  id: string;
+  name: string;
+  args: readonly string[];
+  polarity: string;
+}>;
+
+// implements REQ-capability-check-policy
+export type CheckPolicyEvaluationInput = Readonly<{
+  policies: readonly ActiveCheckPolicy[];
+  loadErrors: readonly CheckPolicyLoadError[];
+  /** Production symbols (no `executable_for`) that carry a sourceFile. */
+  symbols: readonly PolicySymbol[];
+  /** `[symbol, requirement]` implements edges. */
+  implementsEdges: readonly (readonly [string, string])[];
+  currentRequirements: ReadonlySet<string>;
+  /** `[requirement, fact]` requires_predicate edges. */
+  requiresPredicateEdges: readonly (readonly [string, string])[];
+  predicateFacts: readonly PolicyPredicateFact[];
+  /** Workspace-relative file contents, or undefined when unreadable. */
+  readFile: (path: string) => string | undefined;
+}>;
+
+function toPosix(path: string): string {
+  return path.replaceAll("\\", "/").replace(/^\.\//, "");
+}
+
+/** True for a workspace-relative path that stays inside the workspace. */
+function insideWorkspace(path: string): boolean {
+  return (
+    path !== "" &&
+    !path.startsWith("/") &&
+    !/^[A-Za-z]:\//.test(path) &&
+    path !== ".." &&
+    !path.startsWith("../")
+  );
+}
+
+/**
+ * Workspace-relative POSIX path of a symbol sourceFile, or undefined when it
+ * points outside the workspace. Policies only govern workspace files.
+ */
+// implements REQ-capability-check-policy
+export function workspaceSourcePath(
+  workspaceRoot: string,
+  sourceFile: string,
+): string | undefined {
+  const path = posix.normalize(
+    toPosix(
+      isAbsolute(sourceFile) ? relative(workspaceRoot, sourceFile) : sourceFile,
+    ),
+  );
+  return insideWorkspace(path) ? path : undefined;
+}
+
+function matcher(patterns: readonly string[]): (path: string) => boolean {
+  const matcher = ignore().add([...patterns]);
+  return (path) => {
+    const relative = toPosix(path);
+    // ignore() throws on absolute and ../ paths; neither is in a policy's scope.
+    return insideWorkspace(relative) && matcher.ignores(relative);
+  };
+}
+
+function groupBy<T>(
+  pairs: readonly (readonly [string, T])[],
+): Map<string, T[]> {
+  const grouped = new Map<string, T[]>();
+  for (const [key, value] of pairs) {
+    grouped.set(key, [...(grouped.get(key) ?? []), value]);
+  }
+  return grouped;
+}
+
+/** Asserted predicate names each current requirement is grounded in. */
+function requirementPredicates(
+  input: CheckPolicyEvaluationInput,
+): Map<string, PolicyPredicateFact[]> {
+  const facts = new Map(input.predicateFacts.map((fact) => [fact.id, fact]));
+  const grounded = new Map<string, PolicyPredicateFact[]>();
+  for (const [req, factId] of input.requiresPredicateEdges) {
+    const fact = facts.get(factId);
+    if (!input.currentRequirements.has(req) || fact === undefined) continue;
+    if (fact.polarity !== "assert") continue;
+    grounded.set(req, [...(grounded.get(req) ?? []), fact]);
+  }
+  return grounded;
+}
+
+function ownershipViolations(
+  policy: ActiveCheckPolicy,
+  rule: CheckPolicyOwnershipRule,
+  input: CheckPolicyEvaluationInput,
+  grounded: Map<string, PolicyPredicateFact[]>,
+  owners: Map<string, string[]>,
+): Violation[] {
+  const included = matcher(rule.include);
+  const excluded = matcher(rule.exclude ?? []);
+  const title =
+    rule.symbolTitlePattern !== undefined
+      ? new RegExp(rule.symbolTitlePattern)
+      : undefined;
+  const qualifying = new Set(rule.requirePredicates);
+  const violations: Violation[] = [];
+  for (const symbol of input.symbols) {
+    if (!included(symbol.sourceFile) || excluded(symbol.sourceFile)) continue;
+    if (title !== undefined && !title.test(symbol.title)) continue;
+    if (rule.exemptTag !== undefined && symbol.tags.includes(rule.exemptTag))
+      continue;
+    const requirements = owners.get(symbol.id) ?? [];
+    const owned = requirements.some((req) =>
+      (grounded.get(req) ?? []).some((fact) => qualifying.has(fact.name)),
+    );
+    if (owned) continue;
+    violations.push({
+      rule: POLICY_OWNERSHIP_RULE,
+      entityId: symbol.id,
+      description: `${symbol.id} (${symbol.sourceFile}) is in scope of ${policy.packageName} rule '${rule.id}' but implements no current requirement grounded in ${rule.requirePredicates.join(", ")}`,
+      suggestion: `${rule.description}. Link the symbol with implements to a requirement that carries one of these predicates via requires_predicate, or create that requirement first${rule.exemptTag !== undefined ? `; tag the symbol '${rule.exemptTag}' only when it is intentionally unconstrained` : ""}.`,
+      source: symbol.sourceFile,
+      evidence: {
+        policy: policy.document.id,
+        package: policy.packageName,
+        policyRule: rule.id,
+        requirePredicates: [...rule.requirePredicates],
+        implements: requirements,
+      },
+    });
+  }
+  return violations;
+}
+
+/** Marker text as declared, plus its kebab-case spelling for snake_case atoms. */
+function markerSpellings(marker: string): string[] {
+  return [...new Set([marker, marker.replaceAll("_", "-")])];
+}
+
+function searchedFiles(
+  sourceFile: string,
+  rule: CheckPolicyMarkerRule,
+): string[] {
+  const source = toPosix(sourceFile);
+  const directory = dirname(source);
+  const stem = basename(source, extname(source));
+  const siblings = (rule.siblingExtensions ?? []).map((extension) =>
+    toPosix(join(directory, `${stem}${extension}`)),
+  );
+  return [source, ...siblings.filter((path) => path !== source)];
+}
+
+function markerViolations(
+  policy: ActiveCheckPolicy,
+  rule: CheckPolicyMarkerRule,
+  input: CheckPolicyEvaluationInput,
+  grounded: Map<string, PolicyPredicateFact[]>,
+  owners: Map<string, string[]>,
+): Violation[] {
+  const markersByPattern = new Map<string, string[]>();
+  for (const fact of input.predicateFacts) {
+    if (fact.name !== rule.markerPredicate || fact.polarity !== "assert")
+      continue;
+    const pattern = fact.args[rule.markerPatternArgument];
+    const marker = fact.args[rule.markerArgument];
+    if (pattern === undefined || marker === undefined) continue;
+    markersByPattern.set(pattern, [
+      ...(markersByPattern.get(pattern) ?? []),
+      marker,
+    ]);
+  }
+  const violations: Violation[] = [];
+  // Several symbols in one file (component, props, helpers) share its markers;
+  // report each missing marker once per file and requirement.
+  const reported = new Set<string>();
+  for (const symbol of input.symbols) {
+    for (const req of owners.get(symbol.id) ?? []) {
+      for (const fact of grounded.get(req) ?? []) {
+        if (fact.name !== rule.patternPredicate) continue;
+        const pattern = fact.args[rule.patternArgument];
+        if (pattern === undefined) continue;
+        const files = searchedFiles(symbol.sourceFile, rule);
+        const contents = files
+          .map((path) => input.readFile(path))
+          .filter((content): content is string => content !== undefined);
+        for (const marker of [
+          ...new Set(markersByPattern.get(pattern) ?? []),
+        ]) {
+          const present = markerSpellings(marker).some((spelling) =>
+            contents.some((content) => content.includes(spelling)),
+          );
+          const key = JSON.stringify([files[0], req, marker]);
+          if (present || reported.has(key)) continue;
+          reported.add(key);
+          violations.push({
+            rule: POLICY_MARKERS_RULE,
+            entityId: symbol.id,
+            description: `${symbol.id} implements ${req}, which uses pattern '${pattern}', but none of ${files.join(", ")} contains its marker '${marker}'`,
+            suggestion: `${rule.description}. Restore the pattern in the implementation, or if the design changed on purpose, supersede ${req} with a requirement naming the new pattern.`,
+            source: symbol.sourceFile,
+            evidence: {
+              policy: policy.document.id,
+              package: policy.packageName,
+              policyRule: rule.id,
+              requirement: req,
+              pattern,
+              marker,
+              searchedFiles: files,
+            },
+          });
+        }
+      }
+    }
+  }
+  return violations;
+}
+
+function loadErrorViolations(
+  errors: readonly CheckPolicyLoadError[],
+  rules: ReadonlySet<string>,
+): Violation[] {
+  const rule = POLICY_RULES.find((name) => rules.has(name));
+  if (rule === undefined) return [];
+  return errors.map((error) => ({
+    rule,
+    entityId: error.packageName,
+    description: `Check policy from '${error.packageName}' could not be read: ${error.message}`,
+    suggestion:
+      "Install the activated plugin package in this workspace, or remove its kibi.check-policy.v1 entry from package.json#kibi.plugins. Kibi does not skip an activated policy it cannot read.",
+    evidence: { package: error.packageName },
+  }));
+}
+
+/**
+ * Evaluate active check policies against the KB. Pure: all KB data and file
+ * reads come in through `input`.
+ */
+// implements REQ-capability-check-policy
+export function evaluateCheckPolicies(
+  input: CheckPolicyEvaluationInput,
+  rules: ReadonlySet<string>,
+): Violation[] {
+  const grounded = requirementPredicates(input);
+  const owners = groupBy(
+    input.implementsEdges.filter(([, req]) =>
+      input.currentRequirements.has(req),
+    ),
+  );
+  const violations = loadErrorViolations(input.loadErrors, rules);
+  for (const policy of input.policies) {
+    if (rules.has(POLICY_OWNERSHIP_RULE)) {
+      for (const rule of policy.document.ownership ?? []) {
+        violations.push(
+          ...ownershipViolations(policy, rule, input, grounded, owners),
+        );
+      }
+    }
+    if (rules.has(POLICY_MARKERS_RULE)) {
+      for (const rule of policy.document.markers ?? []) {
+        violations.push(
+          ...markerViolations(policy, rule, input, grounded, owners),
+        );
+      }
+    }
+  }
+  return violations;
+}
+
+async function rows(
+  prolog: Pick<PrologPort, "query">,
+  goal: string,
+  what: string,
+): Promise<string[][]> {
+  const result = await prolog.query(goal);
+  if (!result.success) {
+    throw new Error(
+      `Unable to read ${what} for check policies: ${result.error ?? "query failed"}`,
+    );
+  }
+  return parseListOfLists(result.bindings.Rows ?? "[]");
+}
+
+function atom(value: string | undefined): string {
+  return String(parsePrologValue(value ?? ""));
+}
+
+function stringList(value: unknown): string[] {
+  if (Array.isArray(value)) return value.map(String);
+  if (typeof value === "string" && value !== "") return [value];
+  return [];
+}
+
+function fileReader(
+  workspaceRoot: string,
+): (path: string) => string | undefined {
+  const cache = new Map<string, string | undefined>();
+  return (path) => {
+    if (!insideWorkspace(toPosix(path))) return undefined;
+    if (!cache.has(path)) {
+      try {
+        cache.set(path, fs.readFileSync(join(workspaceRoot, path), "utf8"));
+      } catch {
+        cache.set(path, undefined);
+      }
+    }
+    return cache.get(path);
+  };
+}
+
+/**
+ * Collect policy findings for the selected rules. With no activated check
+ * policy this returns at once, so projects without one pay nothing.
+ */
+// implements REQ-capability-check-policy
+export async function collectCheckPolicyViolations(
+  prolog: Pick<PrologPort, "query">,
+  rules: ReadonlySet<string>,
+  workspaceRoot: string,
+): Promise<Violation[]> {
+  if (!POLICY_RULES.some((rule) => rules.has(rule))) return [];
+  const { policies, errors } = readActiveCheckPolicies(workspaceRoot);
+  if (policies.length === 0) {
+    return loadErrorViolations(errors, rules);
+  }
+  // One Prolog port serves queries in order; read sequentially.
+  const symbolEntities = await loadEntitiesPaged(prolog, "symbol", 200);
+  const testSymbols = new Set(
+    (
+      await rows(
+        prolog,
+        "findall([S], kb:executable_test_symbol(S), Rows0), sort(Rows0, Rows)",
+        "executable test symbols",
+      )
+    ).map(([id]) => atom(id)),
+  );
+  const implementsEdges = (
+    await rows(
+      prolog,
+      "findall([S,R], kb_relationship(implements, S, R), Rows)",
+      "implements relationships",
+    )
+  ).map(([from, to]) => [atom(from), atom(to)] as const);
+  const requiresPredicateEdges = (
+    await rows(
+      prolog,
+      "findall([R,F], kb_relationship(requires_predicate, R, F), Rows)",
+      "requires_predicate relationships",
+    )
+  ).map(([from, to]) => [atom(from), atom(to)] as const);
+  const currentRequirements = new Set(
+    (
+      await rows(
+        prolog,
+        "findall([R], kb:current_req(R), Rows)",
+        "current requirements",
+      )
+    ).map(([id]) => atom(id)),
+  );
+  const predicateFacts = (
+    await rows(
+      prolog,
+      "findall([F,Name,Args,Polarity], kb:predicate_fact(F, _, Name, Args, Polarity), Rows)",
+      "predicate facts",
+    )
+  ).map(([id, name, args, polarity]) => ({
+    id: atom(id),
+    name: atom(name),
+    args: stringList(parsePrologValue(args ?? "[]")),
+    polarity: atom(polarity),
+  }));
+
+  const symbols: PolicySymbol[] = symbolEntities.flatMap((entity) => {
+    const id = String(entity.id ?? "");
+    const sourceFile =
+      typeof entity.sourceFile === "string"
+        ? workspaceSourcePath(workspaceRoot, entity.sourceFile)
+        : undefined;
+    if (id === "" || testSymbols.has(id) || sourceFile === undefined) return [];
+    return [
+      {
+        id,
+        title: String(entity.title ?? id),
+        sourceFile,
+        tags: stringList(entity.tags),
+      },
+    ];
+  });
+
+  return evaluateCheckPolicies(
+    {
+      policies,
+      loadErrors: errors,
+      symbols,
+      implementsEdges,
+      currentRequirements,
+      requiresPredicateEdges,
+      predicateFacts,
+      readFile: fileReader(workspaceRoot),
+    },
+    rules,
+  );
+}

package/src/public/operations/contracts.ts

@@ -489,6 +489,7 @@ const BASE_DATA_SCHEMAS: Readonly<
   kb_find_gaps: objectData({
     rows: recordArray,
     count: integerValue,
+    summary: recordValue,
     meta: recordValue,
   }),
   kb_coverage: objectData({
@@ -603,6 +604,11 @@ const BASE_DATA_SCHEMAS: Readonly<
       tldr: stringValue,
       promptBlock: stringValue,
       recommendedActions: recordArray,
+      pluginOffers: {
+        ...recordArray,
+        description:
+          "Optional plugins that fit this workspace and that the project has neither activated nor declined. Ask the operator; on yes install and activate the package, on no add it to package.json kibi.declinedPlugins.",
+      },
       declaredContext: recordValue,
       discoverySummary: recordValue,
       candidates: recordArray,