kibi-cli 2.24.0 → 2.26.1

package/src/public/operations/decision-firmness.ts

@@ -16,6 +16,7 @@
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 
+import { execFileSync } from "node:child_process";
 import path from "node:path";
 import {
   MIN_WHY_CHANGED_WORDS,
@@ -27,6 +28,10 @@ import {
   supersedeAcknowledgement,
   whyThisChangedWords,
 } from "../../decision-firmness.js";
+import {
+  firmEditGuidance,
+  unapprovedFirmEdit,
+} from "../../firm-decision-edit.js";
 import {
   listLaneMarkdownFiles,
   readText,
@@ -46,6 +51,9 @@ export const DECISION_FIRM_UNREFERENCED_RULE = "decision-firm-unreferenced";
 /** Only a firm decision may supersede a firm decision (blocking). */
 // implements REQ-kb-decision-firmness
 export const DECISION_FIRM_SUPERSEDED_RULE = "decision-firm-superseded";
+/** A firm decision's claim must not change in place without new human words (blocking). */
+// implements REQ-kb-firm-decision-edit
+export const DECISION_FIRM_EDITED_RULE = "decision-firm-edited";
 /** A supersede must say why under "Why this changed" (blocking). */
 // implements REQ-kb-decision-firmness
 export const SUPERSEDES_REASON_MISSING_RULE = "supersedes-reason-missing";
@@ -58,6 +66,7 @@ export const SUPERSEDES_REASON_ACKNOWLEDGED_RULE =
 export const DECISION_FIRMNESS_RULES = [
   DECISION_FIRM_UNREFERENCED_RULE,
   DECISION_FIRM_SUPERSEDED_RULE,
+  DECISION_FIRM_EDITED_RULE,
   SUPERSEDES_REASON_MISSING_RULE,
   SUPERSEDES_REASON_ACKNOWLEDGED_RULE,
 ] as const;
@@ -345,8 +354,81 @@ export function evaluateDecisionFirmness(
   return findings;
 }
 
+/** Reads a workspace-relative file as committed at HEAD; null when absent. */
+// implements REQ-kb-firm-decision-edit
+export type CommittedFileReader = (relativePath: string) => string | null;
+
+/**
+ * The decision files whose working copy differs from HEAD, with a reader for
+ * their committed content; undefined outside a Git checkout or before the
+ * first commit, where there is nothing to compare against.
+ */
+function committedDecisionChanges(
+  workspaceRoot: string,
+): { changed: Set<string>; read: CommittedFileReader } | undefined {
+  try {
+    const listed = execFileSync(
+      "git",
+      ["-C", workspaceRoot, "diff", "--name-only", "--relative", "-z", "HEAD"],
+      { encoding: "utf8", maxBuffer: 64 * 1024 * 1024, stdio: "pipe" },
+    );
+    const changed = new Set(listed.split("\0").filter((name) => name !== ""));
+    const read: CommittedFileReader = (relativePath) => {
+      try {
+        return execFileSync(
+          "git",
+          ["-C", workspaceRoot, "show", `HEAD:./${relativePath}`],
+          { encoding: "utf8", maxBuffer: 64 * 1024 * 1024, stdio: "pipe" },
+        );
+      } catch {
+        return null;
+      }
+    };
+    return { changed, read };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Current firm requirements and ADRs whose claim changed since HEAD without
+ * citing new human words: an in-place edit that bypassed kb_upsert's guard.
+ * A decision new since HEAD, or one that was not firm there, is not judged.
+ */
+// implements REQ-kb-firm-decision-edit
+export function evaluateFirmDecisionEdits(
+  entities: readonly AuthoredEntity[],
+  edges: ReadonlyMap<string, Set<string>>,
+  changed: ReadonlySet<string>,
+  readCommitted: CommittedFileReader,
+): Violation[] {
+  const superseded = supersededIds(edges);
+  const findings: Violation[] = [];
+  for (const entity of [...entities].sort((left, right) =>
+    left.id.localeCompare(right.id),
+  )) {
+    if (!changed.has(entity.path)) continue;
+    if (!isCurrentAuthoredEntity(entity, superseded)) continue;
+    const committed = readCommitted(entity.path);
+    if (committed === null) continue;
+    const before = readAuthoredEntity(committed, entity.path);
+    if (before === null || before.type !== entity.type) continue;
+    const fields = unapprovedFirmEdit(before, entity);
+    if (fields.length === 0) continue;
+    findings.push({
+      rule: DECISION_FIRM_EDITED_RULE,
+      entityId: entity.id,
+      description: `${entity.id} is a firm decision whose ${fields.join(", ")} changed since HEAD without citing new human words`,
+      suggestion: `${firmEditGuidance(entity.type)}. To undo the edit, restore ${entity.path} from HEAD`,
+      source: entity.path,
+      evidence: { type: entity.type, changed: fields },
+    });
+  }
+  return findings;
+}
+
 /** Read the authored decisions once and evaluate the selected rules. */
-// implements REQ-kb-decision-firmness
+// implements REQ-kb-decision-firmness, REQ-kb-firm-decision-edit
 export function collectDecisionFirmnessViolations(
   rules: ReadonlySet<string>,
   workspaceRoot: string,
@@ -354,16 +436,31 @@ export function collectDecisionFirmnessViolations(
   if (!DECISION_FIRMNESS_RULES.some((rule) => rules.has(rule))) return [];
   const entities = listDecisionEntities(workspaceRoot);
   const manifest = readKbManifest(workspaceRoot);
-  return evaluateDecisionFirmness(
-    entities,
-    authoredSupersedes(workspaceRoot, entities),
-    rules,
-    new Set(manifest?.supersedesReasonAcknowledged ?? []),
-    {
-      schemaVersion: manifest?.schemaVersion ?? null,
-      firmSupersedeAcknowledged: new Set(
-        manifest?.firmSupersedeAcknowledged ?? [],
-      ),
-    },
-  );
+  const edges = authoredSupersedes(workspaceRoot, entities);
+  const committed = rules.has(DECISION_FIRM_EDITED_RULE)
+    ? committedDecisionChanges(workspaceRoot)
+    : undefined;
+  const edited = committed
+    ? evaluateFirmDecisionEdits(
+        entities,
+        edges,
+        committed.changed,
+        committed.read,
+      )
+    : [];
+  return [
+    ...edited,
+    ...evaluateDecisionFirmness(
+      entities,
+      edges,
+      rules,
+      new Set(manifest?.supersedesReasonAcknowledged ?? []),
+      {
+        schemaVersion: manifest?.schemaVersion ?? null,
+        firmSupersedeAcknowledged: new Set(
+          manifest?.firmSupersedeAcknowledged ?? [],
+        ),
+      },
+    ),
+  ];
 }

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

@@ -413,6 +413,42 @@ export async function loadEntityIds(
   return parseAtomList(result.bindings.Ids ?? "[]").map(normalizeEntityId);
 }
 
+/**
+ * Id, title and semantic text of every current requirement (open,
+ * in_progress, closed and the legacy active/approved statuses, not superseded),
+ * in id order. Projected rows only: semantic inventories and other large
+ * properties stay in the store.
+ */
+// implements REQ-bootstrap-claim-restatement
+export async function loadCurrentRequirementTexts(
+  prolog: Pick<PrologPort, "query">,
+): Promise<{ id: string; title: string; semanticText: string }[]> {
+  const result = await prolog.query("findall(R, kb:current_req(R), Ids)");
+  if (!result.success) {
+    throw new Error(
+      `Current requirement enumeration failed: ${result.error ?? "Unknown error"}`,
+    );
+  }
+  const ids = parseAtomList(result.bindings.Ids ?? "[]").map(normalizeEntityId);
+  const rows = await loadEntityRows(prolog, ids, [
+    "id",
+    "title",
+    "semantic_text",
+  ]);
+  return rows
+    .filter((row) => row.type === "req")
+    .map((row) => ({
+      id: String(row.id ?? ""),
+      title: typeof row.title === "string" ? row.title : "",
+      semanticText:
+        typeof row.semantic_text === "string" ? row.semantic_text : "",
+    }))
+    .filter((row) => row.id !== "")
+    .sort((left, right) =>
+      left.id < right.id ? -1 : left.id > right.id ? 1 : 0,
+    );
+}
+
 /**
  * Properties a projected entity row keeps: what intent ranking, result
  * summaries and the search answer layer read. Large structured properties

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

@@ -1,6 +1,9 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { compilerFingerprintReason } from "../../commands/sync/cache.js";
+import {
+  compilerFingerprintReason,
+  sourceExtractionFailureReasons,
+} from "../../commands/sync/cache.js";
 import { effectiveFirmness } from "../../decision-firmness.js";
 import { EngineClient } from "../../engine.js";
 import {
@@ -1175,6 +1178,13 @@ export async function executeStatus(
     // A stale-lock takeover heals itself; report it without making the KB stale.
     const takeoverNotice = storeLockTakeoverReason(store.path);
     const compilerReason = compilerFingerprintReason(store.path);
+    // implements REQ-kibi-uncompiled-source-visibility
+    // A source the last sync could not extract is missing from the store
+    // even when every compiled file is current.
+    const extractionReasons =
+      store.state === "healthy"
+        ? sourceExtractionFailureReasons(context.workspaceRoot, store.path)
+        : [];
     const engineReason = engineStatus
       ? {
           code: engineStatus.errorCode ?? "engine_status_unavailable",
@@ -1199,6 +1209,7 @@ export async function executeStatus(
       ...(storeReason ? [storeReason] : []),
       ...(lockReason ? [lockReason] : []),
       ...(compilerReason ? [compilerReason] : []),
+      ...extractionReasons,
       ...(engineReason ? [engineReason] : []),
     ].sort((left, right) =>
       String(left.path ?? "").localeCompare(String(right.path ?? "")),
@@ -1208,6 +1219,11 @@ export async function executeStatus(
       // Source hashes can all match while the compilation itself is lossy, so
       // a compiler contract change alone makes the store stale.
       ...(compilerReason ? { syncState: "stale", dirty: true } : {}),
+      // An authored source sync cannot extract leaves its entities out of
+      // the store, so the KB is not current until the file is fixed.
+      ...(extractionReasons.length > 0
+        ? { syncState: "stale", dirty: true }
+        : {}),
       // A missing or empty store has no stale file to report, yet nothing in
       // it is current: the authored sources were never compiled. (A missing
       // store without authored sources, and an unreadable or incomplete one,

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

@@ -1,6 +1,9 @@
 import { MIGRATION_PLAN_REFUSED } from "../../operations/planning/migration-refusal.js";
 import type { KibiResult, OperationEffect, OperationName } from "./types.js";
 
+export { codedErrorOf } from "../../cli-errors.js";
+export type { CodedErrorFields } from "../../cli-errors.js";
+
 export const KIBI_PROTOCOL_VERSION = 1 as const;
 
 function record(value: unknown): value is Record<string, unknown> {

package/src/public/operations/source-relationship-parity.ts

@@ -1,5 +1,6 @@
 import { execFileSync } from "node:child_process";
 import path from "node:path";
+import { sourceExtractionRemediation } from "../../commands/sync/cache.js";
 import { discoverSourceFiles } from "../../commands/sync/discovery.js";
 import { processExtractions } from "../../commands/sync/extraction.js";
 import { findUntrackedDocumentMatches } from "../../commands/sync/untracked-targets.js";
@@ -210,14 +211,28 @@ export async function collectSourceRelationshipParityViolations(
     true,
     workspaceRoot,
   );
+  // implements REQ-kibi-uncompiled-source-visibility
+  // A source sync cannot extract is missing from the compiled KB with every
+  // entity and relationship it declares: one blocking finding per file names
+  // it, the extraction error and the fix.
   if (extraction.errors.length > 0) {
-    return extraction.errors.map(({ file, message }) => ({
-      rule: "source-relationship-parity",
-      entityId: path.relative(workspaceRoot, file).replaceAll(path.sep, "/"),
-      source: path.relative(workspaceRoot, file).replaceAll(path.sep, "/"),
-      description: `Authored relationship parity could not inspect source: ${message}`,
-      suggestion: "Repair the authored source, then rerun kb_check.",
-    }));
+    return extraction.errors.map(({ file, message }) => {
+      const relative = path
+        .relative(workspaceRoot, file)
+        .replaceAll(path.sep, "/");
+      return {
+        rule: "source-relationship-parity",
+        entityId: relative,
+        source: relative,
+        description: `${relative} cannot be compiled, so the entities and relationships it declares are missing from the KB: ${message}`,
+        suggestion: `${sourceExtractionRemediation(relative, message)} Then rerun kb_check.`,
+        evidence: {
+          direction: "source_extraction",
+          file: relative,
+          error: message,
+        },
+      };
+    });
   }
 
   const authored: RelationshipParityRecord[] = extraction.results.flatMap(

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

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

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 and symbol_semantic_review_needed in structured output.",
+          "When true, include changed-file impact diagnostics such as symbol_granularity_violation, symbol_semantic_review_needed and source_file_unowned in structured output.",
       },
       maxDiagnostics: {
         type: "integer",

package/src/public/operations/specs/mutation-schemas.ts

@@ -129,7 +129,7 @@ export const ENTITY_PROPERTIES_SCHEMA = {
       type: "string",
       enum: ["firm", "default", "exploratory"],
       description:
-        "req/adr only. firm = a human stated it as a rule (needs origin.ref to their words); default (when absent) = delegated or agent choice; exploratory = flagged guess.",
+        "req/adr only. firm = a human stated it as a rule (needs origin.ref to their words); its title, meaning or firmness changes only with new human words (a new origin.ref) or by supersede. default = delegated or agent choice; exploratory = flagged guess. Absent = default if an agent wrote it, else firm.",
     },
     rationale: {
       type: "string",

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

@@ -2,7 +2,7 @@
 id: kibi-bootstrap
 name: kibi-bootstrap
 description: "Use for any Kibi bootstrap or onboarding task: seeding a new or thin knowledge base; reviewing a bootstrap or onboarding plan, preview, or evidence; judging approval readiness or coverage; diagnosing a blocked, partial, or failed bootstrap or its repair; applying an approved bootstrap plan; or asking the human which knowledge sources hold intent. Covers kb_status first, source interview, cited intent claims, read-only kb_plan_bootstrap preview, explicit approval, exact-plan kb_apply_plan, and repair-safe close-out."
-version: 3.13.0
+version: 3.14.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -24,7 +24,7 @@ Make `kb_status` your first tool call on every bootstrap task. This includes rev
 - **Review a supplied plan or preview, or judge approval readiness or coverage:** call `kb_status`, then run your own read-only `kb_plan_bootstrap` preview. Compare it with the supplied one: hash, candidates, citations, `suppressedCandidates`, `sourceOnlySignals`, and diagnostics. Report what is ready, what is missing or uncited, and any conflicts for the human. Do not apply. End with `kb_status`.
 - **Blocked, partial, failed, or repair:** never conclude from `kb_status` alone. Run a read-only `kb_plan_bootstrap` preview and report its eligibility and next-action fields (for example `planEligible`, `nextAction`). If it names operator-only repair such as `doctor`, report it and stop. Read `resources/branch-lifecycle.md` before migration or repair. End with `kb_status`.
 - **New or thin knowledge base, or apply an approved plan:** follow the procedure below.
-- **Knowledge base already seeded** (`activationMode: attached_seeded_handoff`): follow the same procedure. Kibi generates no discovered candidates here, but it still plans the intent claims you declare, deduplicated against the existing KB: claims already in the KB are counted as already in the KB, and a plan of the rest is `ready` and applies with `kb_apply_plan` after approval. Never fall back to one `kb_compile_intent` plus one write per claim while such a plan exists. Use `kb_compile_intent` only for claims the plan could not write (`sourceOnlySignals`, `suppressed_by_activation`, `invalid_write`), and `kb_search`/`kb_query` for existing knowledge.
+- **Knowledge base already seeded** (`activationMode: attached_seeded_handoff`): follow the same procedure. Kibi generates no discovered candidates here, but it still plans the intent claims you declare, deduplicated against the existing KB: a claim whose entity exists, or whose statement or excerpt restates a current requirement (same words once case and punctuation are ignored), is counted as already in the KB with the matched id, and a plan of the rest is `ready` and applies with `kb_apply_plan` after approval. A diagnostic saying a claim "closely restates" a requirement means that claim is still planned: show both to the human before approval, and drop the claim or link the two with `restates` or `supersedes`. Never fall back to one `kb_compile_intent` plus one write per claim while such a plan exists. Use `kb_compile_intent` only for claims the plan could not write (`sourceOnlySignals`, `suppressed_by_activation`, `invalid_write`), and `kb_search`/`kb_query` for existing knowledge.
 
 ## Goal
 

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.17.0
+version: 2.19.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -112,9 +112,11 @@ it is a pointer to the knowledge, never proof. Each line answers one question:
 A file already shown this session gets only the one-line `Kibi: this edit to
 <path> is inside <symbol>` update; the facts and tests from its first snippet
 still apply. `Kibi: no symbol in <path> is linked to a requirement yet` means
-the file is unowned: find the governing requirement with `kb_search` and
-`sourceLocations`, then link a symbol to it with `implements` through
-`kb_upsert`. Without a readable manifest (`Kibi: the hook could not read
+the file is unowned, not that no rule covers it. When the note names
+requirements whose titles share the path's words, `kb_query` each one and
+treat a match as the governing rule; otherwise find it with `kb_search` and
+`sourceLocations`. Link the symbol that implements it (for markup, the
+component that renders it) with `implements` through `kb_upsert`. Without a readable manifest (`Kibi: the hook could not read
 .kb/symbols.yaml`) snippets are off for this session; `kb_query({sourceFile})`
 still answers and `kibi sync` regenerates the manifest. The search tip and the
 `.kb/` note appear once per session and need no action.
@@ -136,7 +138,11 @@ still answers and `kibi sync` regenerates the manifest. The search tip and the
 2. Resolve genuine ambiguity with the human; use `kb_model` for deterministic
    interpretation and typed facts.
 3. Create endpoints before relationships and upsert small batches sequentially.
-   Keep the canonical `REQ-* -> SCEN-* -> TEST-*` chain.
+   Keep the canonical `REQ-* -> SCEN-* -> TEST-*` chain. Recording the
+   behavior a change adds (a requirement with a scenario, and an `implements`
+   link from the symbol) is part of finishing that change, not a separate
+   request: do it without asking. Ask only when the change conflicts with a
+   recorded rule.
 4. Author tracked Markdown/YAML/manifests and relationship shards through Kibi;
    Kibi never Git-stages or commits those files. Do not read or edit `.kb`
    directly.
@@ -368,7 +374,11 @@ Search answers, `kb_query` rows and hook snippets show it (snippets label only
   wrote it (`origin.kind: agent`): rules people wrote, imported or carried
   over from before origins existed are theirs. `kb_check` blocks an explicit
   `firmness: firm` without `origin.ref` to their words, and a replacement of
-  a firm decision that is not itself firm.
+  a firm decision that is not itself firm. Never edit a firm decision's
+  title, statement or (ADR) body in place, by `kb_upsert` or on disk:
+  `kb_upsert` refuses it and `kb_check` reports `decision-firm-edited`
+  unless the edit cites new human words in `origin.ref`. Context sections,
+  tags, status and links stay editable.
 - `default`: a delegated or agent choice (`firmness: default`, or an
   agent-written decision without `firmness`). Follow it; supersede it only on
   evidence that it is wrong (a failing test, a measured cost, a constraint it
@@ -381,7 +391,8 @@ conflict a person has to decide. Name the rule (id and what it requires) and
 ask whether to change it; do not implement the request and do not supersede
 the rule. Go ahead only when the person has said to change that rule, in this
 task or in reply: then supersede it with `firmness: firm` and `origin.ref` to
-their words, and say in the final answer which rule changed.
+their words (or, for a correction they asked for in place, update it with
+`origin.ref` to those words), and say in the final answer which rule changed.
 
 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