kibi-cli 0.12.8 → 0.14.0

package/src/public/impact/symbol-quality-model.ts

@@ -0,0 +1,171 @@
+import type { ExtractionResult } from "../../extractors/markdown.js";
+import type { ExtractedSymbol } from "../../traceability/symbol-extract.js";
+import {
+  type SymbolKind,
+  type SymbolRole,
+  getSymbolRole,
+} from "../symbol-granularity.js";
+import type { SymbolQualityDiagnosticsOptions } from "./types.js";
+
+export type SymbolMetadata = {
+  readonly result: ExtractionResult;
+  readonly id: string;
+  readonly title: string;
+  readonly sourceFile: string;
+  readonly source: string;
+  readonly kind: SymbolKind | "component" | "service" | "module" | "config";
+  readonly role: SymbolRole;
+  readonly requirementTargetIds: readonly string[];
+  readonly coordinateKey: string | null;
+};
+
+export const AGGREGATE_KINDS: ReadonlySet<string> = new Set([
+  "class",
+  "component",
+  "service",
+  "module",
+]);
+
+function isActiveSymbol(result: ExtractionResult): boolean {
+  return result.entity.type === "symbol" && result.entity.status === "active";
+}
+
+function getRequirementTargets(result: ExtractionResult): readonly string[] {
+  return [
+    ...new Set(
+      result.relationships
+        .filter(
+          (relationship) =>
+            relationship.type === "implements" &&
+            relationship.to.startsWith("REQ-"),
+        )
+        .map((relationship) => relationship.to),
+    ),
+  ].sort();
+}
+
+function inferKind(result: ExtractionResult): SymbolMetadata["kind"] {
+  const explicitKind = result.entity.symbol_kind;
+  if (
+    explicitKind === "component" ||
+    explicitKind === "service" ||
+    explicitKind === "module" ||
+    explicitKind === "config"
+  ) {
+    return explicitKind;
+  }
+  if (
+    explicitKind === "function" ||
+    explicitKind === "class" ||
+    explicitKind === "method" ||
+    explicitKind === "property" ||
+    explicitKind === "accessor" ||
+    explicitKind === "interface" ||
+    explicitKind === "type" ||
+    explicitKind === "variable" ||
+    explicitKind === "enum" ||
+    explicitKind === "unknown"
+  ) {
+    return explicitKind;
+  }
+
+  if (result.entity.title.endsWith("Component")) return "component";
+  if (result.entity.title.endsWith("Service")) return "service";
+  if (result.entity.title.endsWith("Module")) return "module";
+  if (result.entity.title.endsWith("Config")) return "config";
+  if (result.entity.title.includes(".")) return "method";
+  return "unknown";
+}
+
+function inferRole(
+  result: ExtractionResult,
+  kind: SymbolMetadata["kind"],
+): SymbolRole {
+  const explicitRole = result.entity.symbol_role;
+  if (
+    explicitRole === "behavioral" ||
+    explicitRole === "structural" ||
+    explicitRole === "type-shape" ||
+    explicitRole === "config" ||
+    explicitRole === "module" ||
+    explicitRole === "unknown"
+  ) {
+    return explicitRole;
+  }
+  if (kind === "component" || kind === "service") return "behavioral";
+  if (kind === "module") return "module";
+  if (kind === "config") return "config";
+  return getSymbolRole({ name: result.entity.title, kind });
+}
+
+function getCoordinateKey(result: ExtractionResult): string | null {
+  const { sourceLine, sourceColumn, sourceEndLine, sourceEndColumn } =
+    result.entity;
+  if (
+    sourceLine === undefined ||
+    sourceColumn === undefined ||
+    sourceEndLine === undefined ||
+    sourceEndColumn === undefined
+  ) {
+    return null;
+  }
+
+  return `${sourceLine}:${sourceColumn}:${sourceEndLine}:${sourceEndColumn}`;
+}
+
+export function collectSymbols(
+  options: SymbolQualityDiagnosticsOptions,
+): readonly SymbolMetadata[] {
+  return options.manifestResults
+    .filter((result) =>
+      options.activeEntityIds === undefined
+        ? isActiveSymbol(result)
+        : isActiveSymbol(result) &&
+          options.activeEntityIds.has(result.entity.id),
+    )
+    .flatMap((result) => {
+      if (result.sourceFile === undefined) return [];
+      const kind = inferKind(result);
+      return [
+        {
+          result,
+          id: result.entity.id,
+          title: result.entity.title,
+          sourceFile: result.sourceFile,
+          source: result.entity.source,
+          kind,
+          role: inferRole(result, kind),
+          requirementTargetIds: getRequirementTargets(result),
+          coordinateKey: getCoordinateKey(result),
+        },
+      ];
+    });
+}
+
+export function isModuleOrConfig(symbol: SymbolMetadata): boolean {
+  return symbol.role === "module" || symbol.role === "config";
+}
+
+export function narrowerManifestSymbols(
+  symbol: SymbolMetadata,
+  symbols: readonly SymbolMetadata[],
+): readonly SymbolMetadata[] {
+  return symbols.filter(
+    (candidate) =>
+      candidate.id !== symbol.id &&
+      candidate.sourceFile === symbol.sourceFile &&
+      candidate.title.startsWith(`${symbol.title}.`),
+  );
+}
+
+export function narrowerExtractedSymbols(
+  symbol: SymbolMetadata,
+  symbolsByFile: ReadonlyMap<string, readonly ExtractedSymbol[]>,
+): readonly ExtractedSymbol[] {
+  return (symbolsByFile.get(symbol.sourceFile) ?? []).filter(
+    (candidate) =>
+      candidate.name !== symbol.title &&
+      candidate.name.startsWith(`${symbol.title}.`) &&
+      candidate.role === "behavioral",
+  );
+}

package/src/public/impact/symbol-quality.ts

@@ -0,0 +1,207 @@
+import type { ExtractionResult } from "../../extractors/markdown.js";
+import type { KibiImpactDiagnostic } from "../../traceability/staged-diagnostics.js";
+import { isAllowedGranularityReason } from "../symbol-granularity.js";
+import {
+  AGGREGATE_KINDS,
+  type SymbolMetadata,
+  collectSymbols,
+  isModuleOrConfig,
+  narrowerExtractedSymbols,
+  narrowerManifestSymbols,
+} from "./symbol-quality-model.js";
+import type { SymbolQualityDiagnosticsOptions } from "./types.js";
+
+function thresholdFor(symbol: SymbolMetadata): number {
+  return AGGREGATE_KINDS.has(symbol.kind) ? 4 : 2;
+}
+
+function isMultiRequirementCandidate(symbol: SymbolMetadata): boolean {
+  if (isModuleOrConfig(symbol)) {
+    return !isAllowedGranularityReason(symbol.result.entity.granularity_reason);
+  }
+  return symbol.role === "behavioral";
+}
+
+function createMultiRequirementDiagnostics(
+  symbols: readonly SymbolMetadata[],
+): readonly KibiImpactDiagnostic[] {
+  return symbols.flatMap((symbol) => {
+    if (!isMultiRequirementCandidate(symbol)) return [];
+    const threshold = thresholdFor(symbol);
+    if (symbol.requirementTargetIds.length <= threshold) return [];
+
+    return [
+      {
+        id: "multi_requirement_symbol_review",
+        severity: "review",
+        blocking: false,
+        category: "symbol",
+        entityId: symbol.id,
+        source: symbol.source,
+        files: [symbol.source, symbol.sourceFile],
+        docs: ["docs/symbol-traceability-taxonomy.md"],
+        message: `Symbol ${symbol.id} implements ${symbol.requirementTargetIds.length} requirements, above the ${threshold} target review threshold.`,
+        suggestion:
+          "Review whether this symbol owns multiple unrelated behaviors; move relationships to narrower behavioral symbols or add a valid granularity_reason when broad ownership is intentional.",
+        evidence: {
+          targetIds: symbol.requirementTargetIds,
+          targetCount: symbol.requirementTargetIds.length,
+          threshold,
+          symbolKind: symbol.kind,
+          symbolRole: symbol.role,
+          sourceFile: symbol.sourceFile,
+        },
+      },
+    ];
+  });
+}
+
+function hasDistinctCoordinates(symbols: readonly SymbolMetadata[]): boolean {
+  const coordinateKeys = symbols.map((symbol) => symbol.coordinateKey);
+  if (coordinateKeys.some((key) => key === null)) return false;
+  return new Set(coordinateKeys).size === coordinateKeys.length;
+}
+
+function createDuplicateCoordinateDiagnostics(
+  symbols: readonly SymbolMetadata[],
+): readonly KibiImpactDiagnostic[] {
+  const groups = Map.groupBy(
+    symbols,
+    (symbol) => `${symbol.sourceFile}\u0000${symbol.title}`,
+  );
+
+  return [...groups.values()].flatMap((group) => {
+    if (group.length < 2) return [];
+    if (hasDistinctCoordinates(group)) return [];
+    const first = group[0];
+    if (first === undefined) return [];
+    const candidateIds = group.map((symbol) => symbol.id).sort();
+
+    return [
+      {
+        id: "duplicate_symbol_coordinate_review",
+        severity: "review",
+        blocking: false,
+        category: "coordinate",
+        entityId: first.id,
+        source: first.source,
+        files: [first.source, first.sourceFile],
+        docs: ["docs/symbol-traceability-taxonomy.md"],
+        message: `Symbols ${candidateIds.join(", ")} share title ${first.title} and source ${first.sourceFile} without distinct coordinate evidence.`,
+        suggestion:
+          "Refresh symbol coordinates or rename member-level manifest entries so duplicate modeled symbols are distinguishable after parsing.",
+        evidence: {
+          candidateIds,
+          title: first.title,
+          sourceFile: first.sourceFile,
+        },
+      },
+    ];
+  });
+}
+
+function requirementTagsById(
+  results: readonly ExtractionResult[],
+): ReadonlyMap<string, readonly string[]> {
+  const tagsById = new Map<string, readonly string[]>();
+  for (const result of results) {
+    if (result.entity.type !== "req") continue;
+    tagsById.set(result.entity.id, [...(result.entity.tags ?? [])].sort());
+  }
+  return tagsById;
+}
+
+function tagsForTargets(
+  targetIds: readonly string[],
+  tagsByRequirementId: ReadonlyMap<string, readonly string[]>,
+): readonly string[] {
+  return [
+    ...new Set(
+      targetIds.flatMap((targetId) => tagsByRequirementId.get(targetId) ?? []),
+    ),
+  ].sort();
+}
+
+function hasSharedRequirementTag(
+  targetIds: readonly string[],
+  tagsByRequirementId: ReadonlyMap<string, readonly string[]>,
+): boolean {
+  const tagSets = targetIds
+    .map((targetId) => new Set(tagsByRequirementId.get(targetId) ?? []))
+    .filter((tagSet) => tagSet.size > 0);
+  const first = tagSets[0];
+  if (first === undefined || tagSets.length !== targetIds.length) return false;
+  return [...first].some((tag) => tagSets.every((tagSet) => tagSet.has(tag)));
+}
+
+function isMixedPurposeCandidate(symbol: SymbolMetadata): boolean {
+  return AGGREGATE_KINDS.has(symbol.kind) || isModuleOrConfig(symbol);
+}
+
+function createMixedPurposeDiagnostics(
+  symbols: readonly SymbolMetadata[],
+  options: SymbolQualityDiagnosticsOptions,
+): readonly KibiImpactDiagnostic[] {
+  const tagsByRequirementId = requirementTagsById(options.manifestResults);
+  return symbols.flatMap((symbol) => {
+    if (!isMixedPurposeCandidate(symbol)) return [];
+    const manifestChildren = narrowerManifestSymbols(symbol, symbols);
+    const extractedChildren = narrowerExtractedSymbols(
+      symbol,
+      options.symbolsByFile,
+    );
+    if (manifestChildren.length === 0 && extractedChildren.length === 0)
+      return [];
+    const requirementTags = tagsForTargets(
+      symbol.requirementTargetIds,
+      tagsByRequirementId,
+    );
+    if (requirementTags.length < 3) return [];
+    if (
+      hasSharedRequirementTag(symbol.requirementTargetIds, tagsByRequirementId)
+    ) {
+      return [];
+    }
+    const narrowerSymbolIds = [
+      ...new Set([
+        ...manifestChildren.map((child) => child.id),
+        ...extractedChildren.map((child) => child.id),
+      ]),
+    ].sort();
+
+    return [
+      {
+        id: "component_mixed_purpose_review",
+        severity: "review",
+        blocking: false,
+        category: "mixed-purpose",
+        entityId: symbol.id,
+        source: symbol.source,
+        files: [symbol.source, symbol.sourceFile],
+        docs: ["docs/symbol-traceability-taxonomy.md"],
+        message: `Symbol ${symbol.id} spans unrelated requirement tag clusters while narrower same-file symbols exist.`,
+        suggestion:
+          "Move unrelated requirement ownership to narrower class members/components/services or split the coarse symbol into cohesive behavioral anchors.",
+        evidence: {
+          targetIds: symbol.requirementTargetIds,
+          requirementTags,
+          narrowerSymbolIds,
+          sourceFile: symbol.sourceFile,
+          symbolKind: symbol.kind,
+          symbolRole: symbol.role,
+        },
+      },
+    ];
+  });
+}
+
+export function createSymbolQualityDiagnostics(
+  options: SymbolQualityDiagnosticsOptions,
+): KibiImpactDiagnostic[] {
+  const symbols = collectSymbols(options);
+  return [
+    ...createMultiRequirementDiagnostics(symbols),
+    ...createDuplicateCoordinateDiagnostics(symbols),
+    ...createMixedPurposeDiagnostics(symbols, options),
+  ];
+}

package/src/public/impact/types.ts

@@ -0,0 +1,99 @@
+import type { ExtractionResult } from "../../extractors/markdown.js";
+import type { HunkRange, StagedFile } from "../../traceability/git-staged.js";
+import type { KibiImpactDiagnostic } from "../../traceability/staged-diagnostics.js";
+import type { ExtractedSymbol } from "../../traceability/symbol-extract.js";
+
+export type QualityDiagnosticSeverity = "error" | "warning" | "review" | "info";
+
+export type QualityDiagnostic = {
+  readonly id: string;
+  readonly severity: QualityDiagnosticSeverity;
+  readonly blocking: boolean;
+  readonly category:
+    | "symbol"
+    | "requirement"
+    | "coverage"
+    | "fact"
+    | "status"
+    | "coordinate"
+    | "mixed-purpose"
+    | string;
+  readonly entityId?: string;
+  readonly source?: string;
+  readonly files?: readonly string[];
+  readonly docs?: readonly string[];
+  readonly message: string;
+  readonly suggestion: string;
+  readonly evidence?: Readonly<Record<string, unknown>>;
+};
+
+export type SymbolsByFile = Map<string, readonly ExtractedSymbol[]>;
+
+export type TraceabilityRelationship = {
+  readonly type: string;
+  readonly to: string;
+};
+
+export type SymbolGranularityDiagnosticsOptions = {
+  readonly manifestResults: readonly ExtractionResult[];
+  readonly activeEntityIds?: ReadonlySet<string>;
+  readonly symbolsByFile: SymbolsByFile;
+  readonly sourceContentByFile?: ReadonlyMap<string, string>;
+  readonly workspaceRoot?: string;
+};
+
+export type SemanticReviewDiagnosticsOptions = {
+  readonly symbolsByFile: SymbolsByFile;
+};
+
+export type SymbolQualityDiagnosticsOptions = {
+  readonly manifestResults: readonly ExtractionResult[];
+  readonly activeEntityIds?: ReadonlySet<string>;
+  readonly symbolsByFile: SymbolsByFile;
+};
+
+export type RequirementQualityDiagnosticsOptions = {
+  readonly manifestResults: readonly ExtractionResult[];
+  readonly hardViolationEntityIds?: ReadonlySet<string>;
+};
+
+export type ChangedFileImpactOptions = {
+  readonly workspaceRoot: string;
+  readonly sourceFiles?: readonly string[];
+  readonly staged?: boolean;
+  readonly includeWorkingTreeDiff?: boolean;
+  readonly includeImpactDiagnostics?: boolean;
+  readonly maxDiagnostics?: number;
+};
+
+export type ImpactExtractedSymbol = {
+  readonly id: string;
+  readonly name: string;
+  readonly kind: string;
+  readonly role: string;
+  readonly location: ExtractedSymbol["location"];
+  readonly hunkRanges: readonly HunkRange[];
+  readonly linkedEntityIds: readonly string[];
+};
+
+export type ImpactLinkedEntity = {
+  readonly id: string;
+  readonly relationshipType: string;
+  readonly sourceSymbolId: string;
+  readonly sourceSymbolName: string;
+};
+
+export type ChangedFileImpactResult = {
+  readonly impactDiagnostics: readonly KibiImpactDiagnostic[];
+  readonly sourceFiles: readonly string[];
+  readonly extractedSymbols: readonly ImpactExtractedSymbol[];
+  readonly linkedEntities: readonly ImpactLinkedEntity[];
+  readonly nextActions: readonly string[];
+};
+
+export type SourceChange = {
+  readonly file: string;
+  readonly status: StagedFile["status"];
+  readonly hunkRanges: readonly HunkRange[];
+  readonly content: string;
+};

package/src/public/impact-diagnostics.ts

@@ -0,0 +1,22 @@
+export { analyzeChangedFileImpact } from "./impact/analyzer.js";
+export { collectFullKbQualityDiagnostics } from "./impact/full-kb-quality.js";
+export {
+  createSemanticReviewDiagnostics,
+  createSymbolGranularityDiagnostics,
+  hasBlockingImpactDiagnostics,
+  hasBlockingQualityDiagnostics,
+} from "./impact/diagnostics.js";
+export { createRequirementQualityDiagnostics } from "./impact/requirement-quality.js";
+export { createSymbolQualityDiagnostics } from "./impact/symbol-quality.js";
+export type {
+  ChangedFileImpactOptions,
+  ChangedFileImpactResult,
+  ImpactExtractedSymbol,
+  ImpactLinkedEntity,
+  QualityDiagnostic,
+  QualityDiagnosticSeverity,
+  RequirementQualityDiagnosticsOptions,
+  SemanticReviewDiagnosticsOptions,
+  SymbolGranularityDiagnosticsOptions,
+  SymbolQualityDiagnosticsOptions,
+} from "./impact/types.js";

package/src/public/schemas/entity.ts

@@ -29,6 +29,8 @@ type FactKind =
 type Operator = "eq" | "neq" | "lt" | "lte" | "gt" | "gte";
 type ValueType = "string" | "int" | "number" | "bool";
 type Polarity = "require" | "forbid" | "assert" | "deny";
+type VerificationScope = "unit" | "integration" | "end_to_end";
+type VerificationPerspective = "internal" | "consumer";
 
 const factConditionals = JSON.parse(`[
   {
@@ -133,6 +135,14 @@ const entitySchema: Record<string, unknown> = {
       type: "string",
       enum: [...SYMBOL_ROLES] satisfies SymbolRole[],
     },
+    verification_scope: {
+      type: "string",
+      enum: ["unit", "integration", "end_to_end"] satisfies VerificationScope[],
+    },
+    verification_perspective: {
+      type: "string",
+      enum: ["internal", "consumer"] satisfies VerificationPerspective[],
+    },
     type: {
       type: "string",
       enum: [
@@ -235,6 +245,19 @@ const entitySchema: Record<string, unknown> = {
         },
       },
     },
+    {
+      if: {
+        properties: { type: { const: "test" } },
+      },
+      else: {
+        not: {
+          anyOf: [
+            { required: ["verification_scope"] },
+            { required: ["verification_perspective"] },
+          ],
+        },
+      },
+    },
     ...factConditionals,
   ],
   additionalProperties: false,

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

@@ -101,7 +101,7 @@ See `resources/fact-lanes.md` for the full strict vs observation lane comparison
 
 Model one semantic claim per strict `property_value` fact. Reusing the same `subject_key` and `property_key` lets `domain-contradictions` compare requirements mechanically.
 
-Incoherent role-set example: `REQ-ROLE-SET-2` says the allowed user roles are exactly `[user, admin]`, while `REQ-ROLE-SET-3` says the same property is exactly `[user, admin, superadmin]`. Both constrain `FACT-USER-ROLES` and require different values for `user.roles.allowed_set`, so they cannot both be current.
+Incoherent role-set example: `REQ-ROLE-SET-2` says the allowed user roles are exactly `user,admin`, while `REQ-ROLE-SET-3` says the same property is exactly `user,admin,superadmin`. Both constrain `FACT-USER-ROLES` and require different values for `user.roles.allowed_set`, so they cannot both be current.
 
 ```yaml
 subject:
@@ -115,15 +115,15 @@ property_values:
     subject_key: user.roles
     property_key: user.roles.allowed_set
     operator: eq
-    value_type: list
-    value_json: '["user", "admin"]'
+    value_type: string
+    value_string: user,admin
   - id: FACT-USER-ROLES-ALLOWED-3
     fact_kind: property_value
     subject_key: user.roles
     property_key: user.roles.allowed_set
     operator: eq
-    value_type: list
-    value_json: '["user", "admin", "superadmin"]'
+    value_type: string
+    value_string: user,admin,superadmin
 
 requirements:
   - id: REQ-ROLE-SET-2
@@ -176,6 +176,14 @@ Keep symbol payloads minimal: include only the fields needed to identify the sym
 
 When a generic `Query failed` appears, do not keep retrying the same payload. First call `kb_validate_upsert`, query or create the missing endpoints, reduce the payload to the minimum required fields, and retry once. If it still fails, report the blocker instead of looping.
 
+## Small Behavior Fix Impact Evidence
+
+For a behavior-changing source edit with no existing requirement, create a requirement for the corrected behavior. If no requirement exists, create one for the corrected behavior, then model strict facts from that requirement when the invariant is contradiction-sensitive.
+
+Do not link facts directly to tests. Facts describe the invariant; requirements or scenarios are verified by executable tests. Use `REQ -> TEST` with `verified_by` or `TEST -> REQ` with `validates`, then link the requirement to facts with `constrains` and `requires_property`. Link the touched production symbol to the requirement with `implements` and to the test with `covered_by` when coverage evidence is needed.
+
+MCP writes do not automatically stage markdown evidence. When a staged hook requires impact evidence, ensure the repo's tracked documentation artifacts for the requirement, fact, test, symbol metadata, or coordinate refresh are authored and staged alongside the source change.
+
 ## Sequential Upserts
 
 Never fire `kb_upsert` calls in parallel. Execute them sequentially to avoid lock contention and ensure deterministic ordering. This is especially important when creating chains of related entities.

package/src/public/skills/kibi-usage/resources/fact-lanes.md

@@ -30,7 +30,7 @@ Granular strict facts work best when each `property_value` represents one semant
 
 ### Role set conflict
 
-`REQ-ROLE-SET-2` and `REQ-ROLE-SET-3` are incoherent if both are current: they each define the exact allowed role set, but one allows two roles and the other allows three.
+`REQ-ROLE-SET-2` and `REQ-ROLE-SET-3` are incoherent if both are current: they each define the exact allowed role set, but one allows two roles and the other allows three. Encode compact set values as canonical strings because the strict property schema supports string, int, number, and bool values.
 
 ```yaml
 subject:
@@ -48,8 +48,8 @@ property_values:
     subject_key: user.roles
     property_key: user.roles.allowed_set
     operator: eq
-    value_type: list
-    value_json: '["user", "admin"]'
+    value_type: string
+    value_string: user,admin
   - id: FACT-USER-ROLES-ALLOWED-3
     title: User, admin, and superadmin roles
     status: active
@@ -57,8 +57,8 @@ property_values:
     subject_key: user.roles
     property_key: user.roles.allowed_set
     operator: eq
-    value_type: list
-    value_json: '["user", "admin", "superadmin"]'
+    value_type: string
+    value_string: user,admin,superadmin
 
 relationships:
   - { type: constrains, from: REQ-ROLE-SET-2, to: FACT-USER-ROLES }

package/src/public/skills/kibi-usage/resources/relationship-directions.md

@@ -87,3 +87,33 @@ relationships:
     from: SYM-handler
     to: TEST-005
 ```
+
+## Invalid Test-Fact Shortcuts
+
+Do not model small behavior fixes as direct test-fact pairs. Facts describe invariants; requirements or scenarios are verified by tests.
+
+```yaml
+# WRONG: fact -> test is not a valid verified_by shape
+relationships:
+  - type: verified_by
+    from: FACT-HEADER-AVATAR-INITIAL-UPPERCASE
+    to: TEST-AVATAR-HEADER-FALLBACK
+
+# WRONG: test -> fact is not a valid validates shape
+relationships:
+  - type: validates
+    from: TEST-AVATAR-HEADER-FALLBACK
+    to: FACT-HEADER-AVATAR-INITIAL-UPPERCASE
+```
+
+Use a requirement as the verification target/source, then link that requirement to strict facts:
+
+```yaml
+relationships:
+  - type: verified_by
+    from: REQ-HEADER-AVATAR-INITIAL-UPPERCASE
+    to: TEST-AVATAR-HEADER-FALLBACK
+  - type: requires_property
+    from: REQ-HEADER-AVATAR-INITIAL-UPPERCASE
+    to: FACT-HEADER-AVATAR-INITIAL-UPPERCASE
+```

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

@@ -19,6 +19,20 @@ The canonical workflow for any KB operation follows this pattern:
 4. kb_check with targeted rules
 ```
 
+## Small Behavior Fix With No Existing Requirement
+```
+1. kb_search and kb_query by the changed source file and test file.
+2. If no requirement exists, create a REQ for the corrected behavior.
+3. Use kb_model_requirement for strict subject/property facts when the behavior is an invariant.
+4. Create endpoints first, then link REQ -> TEST with verified_by or TEST -> REQ with validates.
+5. Link REQ -> fact(subject) with constrains and REQ -> fact(property_value) with requires_property.
+6. Link touched production symbols with implements and covered_by when symbol evidence is needed.
+7. Author and stage tracked markdown/symbol evidence; MCP writes do not stage those files automatically.
+8. Run kb_check with targeted rules, then a final full check.
+```
+
+Do not create a test-fact pair. Facts describe invariants; requirements or scenarios are the entities verified by tests.
+
 ## Fixing a Traceability Gap
 ```
 1. kb_query --sourceFile <code-file> to find linked entities