kibi-cli 2.21.0 → 2.22.0

package/src/public/operations/symbol-granularity-check.ts

@@ -0,0 +1,233 @@
+/*
+ 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 { readFileSync, statSync } from "node:fs";
+import * as path from "node:path";
+import type { ExtractionResult } from "../../extractors/markdown.js";
+import { createMaintenanceSourceAnalysisService } from "../../plugins/maintenance-source-analysis.js";
+import {
+  normalizeEntityId,
+  parseEntityFromList,
+  parseListOfLists,
+  parseTriples,
+} from "../../prolog/codec.js";
+import {
+  type ExtractedSymbol,
+  extractSymbolsFromStagedFileAsync,
+} from "../../traceability/symbol-extract.js";
+import type { Violation } from "../../utils/rule-registry.js";
+import { createSymbolGranularityDiagnostics } from "../impact/diagnostics.js";
+import { createImpactManifestLookup } from "../impact/manifest.js";
+import { normalizeSourceFile } from "../impact/source-changes.js";
+import {
+  isAllowedGranularityReason,
+  isTraceabilityRelationshipType,
+} from "../symbol-granularity.js";
+import type { PrologPort } from "./runtime-types.js";
+
+/**
+ * Full-check form of the staged gate's `symbol_granularity_violation`: a
+ * symbol with traceability relationships must not link its source file
+ * coarsely while narrower behavioral symbols are available, unless it carries
+ * an allowed granularity_reason.
+ */
+// implements REQ-cli-check, REQ-cli-staged-impact-enforcement
+export const SYMBOL_GRANULARITY_RULE = "symbol-granularity";
+
+const SYMBOL_ROWS_QUERY =
+  "findall([Id,symbol,Fields], (kb_entity(Id, symbol, Props), include([Key=_]>>memberchk(Key, [title,status,source,sourceFile,granularity_reason]), Props, Fields)), Rows)";
+const SYMBOL_RELATIONSHIPS_QUERY =
+  "findall([From,To,Type], (member(Type, [implements,covered_by,executable_for]), kb_relationship(Type, From, To), kb_entity(From, symbol, _)), Rels)";
+
+function stringField(
+  entity: Record<string, unknown>,
+  key: string,
+): string | undefined {
+  const value = entity[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+// implements REQ-cli-check
+async function loadSymbolResults(
+  prolog: Pick<PrologPort, "query">,
+  workspaceRoot: string,
+): Promise<ExtractionResult[]> {
+  const rows = await prolog.query(SYMBOL_ROWS_QUERY);
+  if (!rows.success) {
+    throw new Error(
+      `symbol-granularity symbol projection failed: ${rows.error ?? "unknown error"}`,
+    );
+  }
+  const rels = await prolog.query(SYMBOL_RELATIONSHIPS_QUERY);
+  if (!rels.success) {
+    throw new Error(
+      `symbol-granularity relationship projection failed: ${rels.error ?? "unknown error"}`,
+    );
+  }
+
+  const relationships = new Map<string, ExtractionResult["relationships"]>();
+  for (const [rawFrom, rawTo, type] of parseTriples(
+    rels.bindings.Rels ?? "[]",
+  )) {
+    const from = normalizeEntityId(rawFrom);
+    const current = relationships.get(from) ?? [];
+    current.push({ from, to: normalizeEntityId(rawTo), type });
+    relationships.set(from, current);
+  }
+
+  const results: ExtractionResult[] = [];
+  for (const row of parseListOfLists(rows.bindings.Rows ?? "[]")) {
+    const entity = parseEntityFromList(row);
+    const id = stringField(entity, "id");
+    const sourceFile = stringField(entity, "sourceFile");
+    if (id === undefined || sourceFile === undefined) continue;
+    const granularityReason = stringField(entity, "granularity_reason");
+    results.push({
+      entity: {
+        id,
+        type: "symbol",
+        title: stringField(entity, "title") ?? "",
+        status: stringField(entity, "status") ?? "",
+        created_at: "",
+        updated_at: "",
+        source: stringField(entity, "source") ?? "",
+        ...(granularityReason !== undefined
+          ? { granularity_reason: granularityReason }
+          : {}),
+      },
+      relationships: relationships.get(id) ?? [],
+      sourceFile: normalizeSourceFile(workspaceRoot, sourceFile),
+    });
+  }
+  return results;
+}
+
+/**
+ * The symbols the staged gate would judge: they carry a traceability
+ * relationship and no allowed granularity_reason. Other symbols are exempt,
+ * so their source files need no analysis.
+ */
+// implements REQ-cli-check
+function granularityCandidates(
+  results: readonly ExtractionResult[],
+): ExtractionResult[] {
+  return results.filter(
+    (result) =>
+      result.relationships.some((relationship) =>
+        isTraceabilityRelationshipType(relationship.type),
+      ) && !isAllowedGranularityReason(result.entity.granularity_reason),
+  );
+}
+
+function readRegularFile(absolutePath: string): string | null {
+  try {
+    if (!statSync(absolutePath).isFile()) return null;
+    return readFileSync(absolutePath, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+// implements REQ-cli-check
+async function analyzeFiles(
+  files: readonly string[],
+  results: readonly ExtractionResult[],
+  workspaceRoot: string,
+): Promise<Map<string, readonly ExtractedSymbol[]>> {
+  const manifestLookup = createImpactManifestLookup(results);
+  const service = createMaintenanceSourceAnalysisService(workspaceRoot);
+  const analyses = new Map<string, readonly ExtractedSymbol[]>();
+  for (const file of files) {
+    const content = readRegularFile(path.resolve(workspaceRoot, file));
+    if (content === null) continue;
+    try {
+      const analysis = await service.analyzeTextV2(file, content);
+      // Only a complete parser-backed analysis decides; the staged gate
+      // reports an incomplete one itself when the file is touched.
+      if (analysis.status !== "ok") continue;
+      const symbols = await extractSymbolsFromStagedFileAsync(
+        {
+          path: file,
+          status: "M",
+          content,
+          hunkRanges: [{ start: 1, end: Number.MAX_SAFE_INTEGER }],
+        },
+        manifestLookup,
+        { analyzeText: async () => analysis },
+      );
+      analyses.set(file, symbols);
+    } catch {
+      // An analysis failure cannot decide anything for this file.
+    }
+  }
+  return analyses;
+}
+
+// implements REQ-cli-check
+function granularityViolations(
+  candidates: readonly ExtractionResult[],
+  sourceSymbolsByFile: ReadonlyMap<string, readonly ExtractedSymbol[]>,
+  workspaceRoot: string,
+): Violation[] {
+  return createSymbolGranularityDiagnostics({
+    manifestResults: candidates.filter(
+      (result) =>
+        result.sourceFile !== undefined &&
+        sourceSymbolsByFile.has(result.sourceFile),
+    ),
+    symbolsByFile: new Map(),
+    sourceSymbolsByFile,
+    workspaceRoot,
+  }).map((diagnostic) => ({
+    rule: SYMBOL_GRANULARITY_RULE,
+    entityId: diagnostic.entityId ?? "",
+    description: diagnostic.message,
+    suggestion: diagnostic.suggestion,
+    ...(diagnostic.source !== undefined ? { source: diagnostic.source } : {}),
+    evidence: {
+      diagnosticId: diagnostic.id,
+      ...(diagnostic.evidence ?? {}),
+    },
+  }));
+}
+
+/**
+ * `symbol-granularity`: the staged gate's granularity predicate, evaluated
+ * for every symbol against its whole working-tree file, every declaration a
+ * candidate as if the file were fully staged. Only files of symbols the gate
+ * would judge are analyzed; a file the source analyzers cannot fully analyze
+ * is skipped.
+ */
+// implements REQ-cli-check, REQ-cli-staged-impact-enforcement
+export async function collectSymbolGranularityViolations(
+  prolog: Pick<PrologPort, "query">,
+  workspaceRoot: string,
+  rules: ReadonlySet<string>,
+): Promise<Violation[]> {
+  if (!rules.has(SYMBOL_GRANULARITY_RULE)) return [];
+  const results = await loadSymbolResults(prolog, workspaceRoot);
+  const candidates = granularityCandidates(results);
+  const files = [
+    ...new Set(candidates.map((result) => result.sourceFile ?? "")),
+  ]
+    .filter((file) => file.length > 0)
+    .sort();
+  if (files.length === 0) return [];
+  const analyses = await analyzeFiles(files, results, workspaceRoot);
+  return granularityViolations(candidates, analyses, workspaceRoot);
+}

package/src/public/schemas/entity.ts

@@ -358,6 +358,12 @@ const entitySchema: Record<string, unknown> = {
     text_ref: { type: "string" },
     // Provenance of any authored entity: who wrote it and on what authority.
     origin: ENTITY_ORIGIN_SCHEMA,
+    firmness: {
+      type: "string",
+      enum: ["firm", "default", "exploratory"],
+      description:
+        "Requirement and ADR only. How firmly the decision was made. firm: a human stated it as a rule; it needs a ref (origin.ref, or approval_ref on a requirement) to their words, and only a human may change it. default (assumed when absent): a delegated or agent choice; a later agent may supersede it with evidence. exploratory: a flagged guess, expected to be revisited.",
+    },
     expects: {
       type: "string",
       enum: ["success", "rejection", "error"],
@@ -713,6 +719,12 @@ const entitySchema: Record<string, unknown> = {
         },
       },
     },
+    {
+      if: {
+        properties: { type: { enum: ["req", "adr"] } },
+      },
+      else: { not: { required: ["firmness"] } },
+    },
     {
       if: {
         properties: { type: { const: "scenario" } },

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

@@ -43,10 +43,12 @@ sequential `kb_upsert`, then run final check and coverage. Kibi authors tracked
 files transactionally but never Git-stages or commits them. Do not read or edit
 `.kb` directly.
 
-Use `kb_delete` only for intentional cleanup. Authored entity deletion returns a
-hash-bound approval plan; requirements normally evolve through a new
-requirement linked with `supersedes`. Relationship deletes patch shards while
-preserving unrelated records.
+Use `kb_delete` only for intentional cleanup; `dryRun: true` previews any
+delete without writing. Authored entity deletion returns `outcome:
+plan_returned` with a hash-bound plan whose `nextActions[0].input` is the exact
+`kb_apply_plan` input; requirements return `supersession_required` and evolve
+through a new requirement linked with `supersedes`. Relationship deletes patch
+shards while preserving unrelated records.
 
 ## Typed recovery and proof
 

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.15.3
+version: 2.16.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -188,8 +188,9 @@ returns `status: error`, `MIGRATION_PLAN_REFUSED` and `data.outcome:
 refused`: nothing changed, so read the action `detail` and get a new plan.
 `data.outcome: reconciliation_required` (status success) means an action
 failed mid-way: inspect its effect before retrying. `kb_delete` of an
-authored entity returns status success with `deleted: 0`; its `errors` say
-why nothing was deleted. If the status is
+authored entity returns status success with `deleted: 0` and `outcome:
+plan_returned` (or `supersession_required` for a requirement): nothing was
+deleted yet, and `nextActions` names the call that does it. If the status is
 `committed_with_repairs`, the mutation already committed: inspect failed effects,
 execute each required repair action in order, and never retry the original
 operation. Record effect failures, followed actions, and unsafe retries in
@@ -302,12 +303,18 @@ authored. Each one is the order the write path accepts.
    between the two writes `kb_check` reports the requirement until the
    second lands.
 3. **Deleting authored entities.** `kb_delete` on an authored entity that
-   is not a requirement (scenario, test, fact, ADR, …) returns a hash-bound
-   `kibi.entity-deletion-plan.v1` in `deletionPlan`; apply it unchanged with
-   `kb_apply_plan` (`plan` plus `approvedPlanHash: plan.planHash`). For an
-   authored requirement the plan carries `supersessionRequired: true` and
-   `kb_apply_plan` refuses it (`REQUIREMENT_SUPERSESSION_REQUIRED`): Kibi
-   never deletes an authored requirement. Evolve it instead with a new
+   is not a requirement (scenario, test, fact, ADR, …) writes nothing and
+   returns `outcome: plan_returned` with a hash-bound
+   `kibi.entity-deletion-plan.v1` in `deletionPlan`. After review, run
+   `nextActions[0]` unchanged: `kb_apply_plan` with its `input` (`plan` plus
+   `approvedPlanHash: plan.planHash`), or repeat the `kb_delete` call with
+   `approvedPlanHash` to apply the freshly computed plan in one step (a
+   changed source fails with `DELETE_PLAN_HASH_MISMATCH`). `dryRun: true`
+   previews relationship and direct deletes without writing. For an
+   authored requirement the result is `outcome: supersession_required`, the
+   plan carries `supersessionRequired: true` and both routes refuse it
+   (`REQUIREMENT_SUPERSESSION_REQUIRED`): Kibi never deletes an authored
+   requirement. Evolve it instead with a new
    requirement linked by `supersedes` and close the old one, or, for an
    agent-origin requirement nobody approved and nothing links to, upsert it
    with `status: closed` (keep its `title`); it stays on disk as history. A
@@ -342,6 +349,29 @@ human sets `approved_by`; `kb_check` flags approvals an agent recorded without
 corroboration. Never fill in an approval yourself. Record why a requirement
 exists in `rationale`, or link the ADR that explains it.
 
+## Decision firmness
+
+Requirements and ADRs carry `firmness`, which says what you may do with them.
+Search answers, `kb_query` rows and hook snippets show it (snippets label only
+`[firm]` and `[exploratory]`; an unlabeled decision is `default`).
+
+- `firm`: a human stated it as a rule. Follow it; to change it, ask first.
+  `kb_check` blocks a firm decision without `origin.ref` to their words, and
+  a replacement of a firm decision that is not itself firm.
+- `default` (when absent): a delegated or agent choice. Follow it unless the
+  task gives evidence against it; then supersede it in the same change and
+  list it under "Decisions I changed" for review, without asking first.
+- `exploratory`: a flagged guess; revisit it when you touch the area.
+
+Set `firmness` from what a human actually said: only their stated rule is
+`firm` (with `origin.ref`); "do whatever" or your own pick is `default`; a
+guess is `exploratory`. A supersede needs `## Why this changed` in the new
+entity's body (at least 12 words): name the evidence (a failing test, a
+measured cost, a constraint the old decision missed, a new requirement) and
+answer the old decision's reasoning; `kb_check` blocks it otherwise. A
+preference is not evidence: propose it instead of superseding. Kibi checks
+only that a firm decision has a reference; never cite words nobody said.
+
 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`.
@@ -421,7 +451,17 @@ a second grounding link would fail, so keep the existing link or apply the
 `kb_delete` of the old link, requirement link; between the last two `kb_check`
 reports both `logic-coverage` and `strict-req-fact-pairing` for the
 requirement, as `expected.kbCheckAfterStep` states; run `kb_check` after the
-last step and apply `rollback` if it is not clean); `provide_argument_bindings` and `record_ontology_gap` mean
+last step and apply `rollback` if it is not clean). `keep_existing_grounding`
+means the requirement already links a predicate fact with the candidate's
+`canonical_key` (`existingGrounding[].matchedBy` is `canonical_key` when the
+claim was worded differently), so write nothing. `extend_requirement` means
+the requirement's proposition ledger has no entry for this text, so a link
+cannot be made and no fact is planned: add the clause to the requirement's
+prose (`mode: "requirement"`, or `kb_upsert` with the extended `semantic_text`
+and the ledger `mode: "analyze"` returns) and call `mode: "predicates"` again.
+Read `decisionConflicts` and its warnings whenever `plan` is null: they name
+the stored decision facts the candidate would contradict and the requirements
+that own them. `provide_argument_bindings` and `record_ontology_gap` mean
 the same as for an ungrounded claim, and the gap observation is not a grounding
 link, so write it exactly as returned (tags, `claim_text`, `document.body`, no
 `claim_key`, no relationships). Record an ontology gap only when no returned schema fits the

package/src/public/skills/kibi-usage/resources/source-authoring.md

@@ -23,8 +23,10 @@ drift diagnostic. Unresolved Git index conflicts are likewise blocking; Kibi
 never chooses a merge winner.
 
 Relationship upserts and relationship deletes patch only the canonical shard,
-preserving unrelated records. Authored entity deletion returns a hash-bound
-plan; approve that plan through `kb_apply_plan`. Evolve requirements with a new
+preserving unrelated records. Authored entity deletion writes nothing and
+returns a hash-bound plan (`outcome: plan_returned`); approve it by running the
+returned `nextActions[0]` (`kb_apply_plan` with `{plan, approvedPlanHash}`)
+unchanged, or by repeating `kb_delete` with `approvedPlanHash`. Evolve requirements with a new
 requirement and `supersedes`, rather than deleting the old semantic claim.
 
 On `committed_with_repairs`, inspect `effects` and execute the typed required

package/src/public/symbol-granularity.ts

@@ -117,6 +117,43 @@ export function getBehavioralSymbolNames(
   ].sort();
 }
 
+/**
+ * The candidates that are narrower than a manifest symbol: members of it
+ * (`Title.member`), or, when the source declares no symbol named like it,
+ * every other declaration in the file.
+ */
+// implements REQ-symbol-behavioral-anchors, REQ-cli-schema-migration
+export function narrowerSymbols<T extends { name: string }>(
+  manifestSymbolName: string,
+  candidates: readonly T[],
+  sourceSymbols: readonly { name: string }[],
+): T[] {
+  const declared = sourceSymbols.some(
+    (symbol) => symbol.name === manifestSymbolName,
+  );
+  return candidates.filter(
+    (candidate) =>
+      candidate.name !== manifestSymbolName &&
+      (candidate.name.startsWith(`${manifestSymbolName}.`) || !declared),
+  );
+}
+
+/**
+ * The behavioral symbols that make a traceability link on
+ * `manifestSymbolName` coarse: the staged granularity gate blocks such a
+ * link unless it carries a granularity_reason, and `kibi migrate` marks
+ * exactly these links legacy-link. Empty when the link is narrow enough.
+ */
+// implements REQ-symbol-behavioral-anchors, REQ-cli-schema-migration
+export function coarseLinkBehavioralNames(
+  manifestSymbolName: string,
+  sourceSymbols: readonly GranularSymbolCandidate[],
+): string[] {
+  return getBehavioralSymbolNames(
+    narrowerSymbols(manifestSymbolName, sourceSymbols, sourceSymbols),
+  );
+}
+
 export function getNonBehavioralSymbolNames(
   candidates: GranularSymbolCandidate[],
 ): string[] {

package/src/schemas/entity.schema.json

@@ -514,6 +514,15 @@
       },
       "additionalProperties": false
     },
+    "firmness": {
+      "type": "string",
+      "enum": [
+        "firm",
+        "default",
+        "exploratory"
+      ],
+      "description": "Requirement and ADR only. How firmly the decision was made. firm: a human stated it as a rule; it needs a ref (origin.ref, or approval_ref on a requirement) to their words, and only a human may change it. default (assumed when absent): a delegated or agent choice; a later agent may supersede it with evidence. exploratory: a flagged guess, expected to be revisited."
+    },
     "expects": {
       "type": "string",
       "enum": [
@@ -1657,6 +1666,25 @@
         }
       }
     },
+    {
+      "if": {
+        "properties": {
+          "type": {
+            "enum": [
+              "req",
+              "adr"
+            ]
+          }
+        }
+      },
+      "else": {
+        "not": {
+          "required": [
+            "firmness"
+          ]
+        }
+      }
+    },
     {
       "if": {
         "properties": {