kibi-cli 2.24.0 → 2.25.0

package/dist/firm-decision-edit.d.ts

@@ -0,0 +1,30 @@
+/** A requirement or ADR as authored: front matter and Markdown body. */
+export type DecisionDocument = Readonly<{
+    type: string;
+    data: Readonly<Record<string, unknown>>;
+    body: string;
+}>;
+/** The parts of a decision's claim an in-place edit may change. */
+export type DecisionClaimField = "title" | "statement" | "body" | "firmness";
+/**
+ * The claim fields that differ between two versions of one decision. A
+ * requirement's claim is its title, its stated meaning and the statement its
+ * body derives (context sections may change freely); an ADR's claim is its
+ * title and whole body. Lowering a firm decision's firmness changes it too.
+ */
+export declare function decisionClaimChanges(before: DecisionDocument, after: DecisionDocument): DecisionClaimField[];
+/**
+ * Whether `after` cites human words `before` did not: the reference a person
+ * gave for this change. Kibi checks that a new reference is present, not that
+ * it is genuine.
+ */
+export declare function citesNewHumanWords(before: DecisionDocument, after: DecisionDocument): boolean;
+/**
+ * The claim fields an edit changes on a firm decision without citing new
+ * human words; empty when the edit is allowed. Only a decision that is firm
+ * before the edit is guarded.
+ */
+export declare function unapprovedFirmEdit(before: DecisionDocument, after: DecisionDocument): DecisionClaimField[];
+/** What to do instead of editing a firm decision in place. */
+export declare function firmEditGuidance(type: string): string;
+//# sourceMappingURL=firm-decision-edit.d.ts.map

package/dist/firm-decision-edit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"firm-decision-edit.d.ts","sourceRoot":"","sources":["../src/firm-decision-edit.ts"],"names":[],"mappings":"AAqBA,wEAAwE;AAExE,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxC,IAAI,EAAE,MAAM,CAAC;CACd,CAAC,CAAC;AAEH,mEAAmE;AAEnE,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,WAAW,GAAG,MAAM,GAAG,UAAU,CAAC;AAiB7E;;;;;GAKG;AAEH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,gBAAgB,EACxB,KAAK,EAAE,gBAAgB,GACtB,kBAAkB,EAAE,CAsBtB;AAED;;;;GAIG;AAEH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,gBAAgB,EACxB,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAMT;AAED;;;;GAIG;AAEH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,gBAAgB,EACxB,KAAK,EAAE,gBAAgB,GACtB,kBAAkB,EAAE,CAStB;AAED,8DAA8D;AAE9D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD"}

package/dist/firm-decision-edit.js

@@ -0,0 +1,90 @@
+/*
+ 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 { effectiveFirmness, firmnessRef } from "./decision-firmness.js";
+import { requirementSemanticText } from "./extractors/markdown.js";
+function normalized(value) {
+    return typeof value === "string" ? value.replace(/\s+/g, " ").trim() : "";
+}
+/**
+ * What a requirement states: its authored `semantic_text`, else the
+ * statement its body derives. Context sections are not part of it.
+ */
+function requirementStatement(document) {
+    const authored = normalized(document.data.semantic_text);
+    return authored !== ""
+        ? authored
+        : normalized(requirementSemanticText(document.body));
+}
+/**
+ * The claim fields that differ between two versions of one decision. A
+ * requirement's claim is its title, its stated meaning and the statement its
+ * body derives (context sections may change freely); an ADR's claim is its
+ * title and whole body. Lowering a firm decision's firmness changes it too.
+ */
+// implements REQ-kb-firm-decision-edit
+export function decisionClaimChanges(before, after) {
+    const changed = [];
+    if (normalized(before.data.title) !== normalized(after.data.title))
+        changed.push("title");
+    if (before.type === "req") {
+        if (requirementStatement(before) !== requirementStatement(after) ||
+            normalized(requirementSemanticText(before.body)) !==
+                normalized(requirementSemanticText(after.body)))
+            changed.push("statement");
+    }
+    else if (normalized(before.body) !== normalized(after.body)) {
+        changed.push("body");
+    }
+    if (effectiveFirmness(before.type, before.data.firmness, before.data.origin) ===
+        "firm" &&
+        effectiveFirmness(after.type, after.data.firmness, after.data.origin) !==
+            "firm")
+        changed.push("firmness");
+    return changed;
+}
+/**
+ * Whether `after` cites human words `before` did not: the reference a person
+ * gave for this change. Kibi checks that a new reference is present, not that
+ * it is genuine.
+ */
+// implements REQ-kb-firm-decision-edit
+export function citesNewHumanWords(before, after) {
+    const ref = firmnessRef({ type: after.type, ...after.data });
+    return (ref !== undefined &&
+        ref !== firmnessRef({ type: before.type, ...before.data }));
+}
+/**
+ * The claim fields an edit changes on a firm decision without citing new
+ * human words; empty when the edit is allowed. Only a decision that is firm
+ * before the edit is guarded.
+ */
+// implements REQ-kb-firm-decision-edit
+export function unapprovedFirmEdit(before, after) {
+    if (effectiveFirmness(before.type, before.data.firmness, before.data.origin) !==
+        "firm")
+        return [];
+    const changed = decisionClaimChanges(before, after);
+    if (changed.length === 0 || citesNewHumanWords(before, after))
+        return [];
+    return changed;
+}
+/** What to do instead of editing a firm decision in place. */
+// implements REQ-kb-firm-decision-edit
+export function firmEditGuidance(type) {
+    return `Ask the person who stated it. If they agree, either write the change with ${type === "req" ? "origin.ref or approval_ref" : "origin.ref"} pointing at their words, or supersede it with a new firmness: firm decision that cites them; otherwise leave it and propose the change`;
+}

package/dist/operations/mutation/firm-decision-guard.d.ts

@@ -0,0 +1,10 @@
+import type { StoredEntityLookup } from "./stored-entity.js";
+import type { UpsertInput } from "./types.js";
+/**
+ * Refuse an upsert that changes a current firm requirement's or ADR's claim
+ * in place unless it cites new human words for the change. The decision is
+ * judged as authored before the write, so dropping its firmness or origin in
+ * the same write does not make it editable.
+ */
+export declare function assertFirmDecisionUnchanged(input: UpsertInput, workspaceRoot: string, lookup: StoredEntityLookup): Promise<void>;
+//# sourceMappingURL=firm-decision-guard.d.ts.map

package/dist/operations/mutation/firm-decision-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"firm-decision-guard.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/firm-decision-guard.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAwB9C;;;;;GAKG;AAEH,wBAAsB,2BAA2B,CAC/C,KAAK,EAAE,WAAW,EAClB,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,IAAI,CAAC,CA2Bf"}

package/dist/operations/mutation/firm-decision-guard.js

@@ -0,0 +1,71 @@
+/*
+ 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 } from "node:fs";
+import path from "node:path";
+import { carriesFirmness } from "../../decision-firmness.js";
+import { firmEditGuidance, unapprovedFirmEdit, } from "../../firm-decision-edit.js";
+import { isCurrentAuthoredEntity, readAuthoredEntity, } from "../../public/operations/entity-context.js";
+function readStoredDocument(workspaceRoot, stored) {
+    const source = stored.source;
+    if (typeof source !== "string" || !source.endsWith(".md"))
+        return undefined;
+    try {
+        const authored = readAuthoredEntity(readFileSync(path.resolve(workspaceRoot, source), "utf8"), source);
+        if (authored === null)
+            return undefined;
+        return {
+            type: authored.type,
+            data: authored.data,
+            body: authored.body,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Refuse an upsert that changes a current firm requirement's or ADR's claim
+ * in place unless it cites new human words for the change. The decision is
+ * judged as authored before the write, so dropping its firmness or origin in
+ * the same write does not make it editable.
+ */
+// implements REQ-kb-firm-decision-edit
+export async function assertFirmDecisionUnchanged(input, workspaceRoot, lookup) {
+    if (!carriesFirmness(input.type))
+        return;
+    const stored = await lookup.entity();
+    if (stored === undefined || stored === null)
+        return;
+    const authored = readStoredDocument(workspaceRoot, stored);
+    const before = authored ?? {
+        type: input.type,
+        data: stored,
+        body: input.document?.body ?? "",
+    };
+    if (!isCurrentAuthoredEntity({ id: input.id, path: "", ...before, data: { ...before.data } }, new Set()))
+        return;
+    const after = {
+        type: input.type,
+        data: { ...before.data, ...input.properties },
+        body: input.document?.body ?? before.body,
+    };
+    const changed = unapprovedFirmEdit(before, after);
+    if (changed.length === 0)
+        return;
+    throw new Error(`Entity validation failed: ${input.id} is a firm decision, so kb_upsert does not change its ${changed.join(", ")} in place. ${firmEditGuidance(input.type)}.`);
+}

package/dist/operations/mutation/upsert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upsert.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/upsert.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAexE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AA4B3E,OAAO,EACL,KAAK,kBAAkB,EAExB,MAAM,oBAAoB,CAAC;AAQ5B,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,eAAe,EAChB,MAAM,YAAY,CAAC;AAsEpB,wBAAgB,gCAAgC,CAC9C,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GAChB,IAAI,CAkBN;AAwCD,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,OAAO,EAAE,gBAAgB,EACzB,MAAM,CAAC,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,OAAO,EAAE,gBAAgB,EACzB,MAAM,CAAC,EAAE,iBAAiB,EAC1B,MAAM,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CA8BvC;AAmCD,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,kEAAkE;IAClE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;CACrC,CAAC,CAAC;AAGH,uFAAuF;AACvF,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC,CAAC,CAAC;AAGH;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,WAAW,GAAG;IACrB,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACtD,GACA,sBAAsB,CASxB;AAGD,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,yEAAyE;IACzE,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACrD,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;CAC3C,CAAC,CAAC;AAGH;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,gBAAgB,CAAC,CAiF3B;AAgDD,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C;;;;;;OAMG;IAEH,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACxC,CAAC,CAAC;AAyBH,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CA2hBzC"}
+{"version":3,"file":"upsert.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/upsert.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAexE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AA6B3E,OAAO,EACL,KAAK,kBAAkB,EAExB,MAAM,oBAAoB,CAAC;AAQ5B,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,eAAe,EAChB,MAAM,YAAY,CAAC;AAsEpB,wBAAgB,gCAAgC,CAC9C,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GAChB,IAAI,CAkBN;AAwCD,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,OAAO,EAAE,gBAAgB,EACzB,MAAM,CAAC,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,OAAO,EAAE,gBAAgB,EACzB,MAAM,CAAC,EAAE,iBAAiB,EAC1B,MAAM,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CA8BvC;AAmCD,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,kEAAkE;IAClE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;CACrC,CAAC,CAAC;AAGH,uFAAuF;AACvF,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC,CAAC,CAAC;AAGH;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,WAAW,GAAG;IACrB,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACtD,GACA,sBAAsB,CASxB;AAGD,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,yEAAyE;IACzE,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACrD,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;CAC3C,CAAC,CAAC;AAGH;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,gBAAgB,CAAC,CAkF3B;AAgDD,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C;;;;;;OAMG;IAEH,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACxC,CAAC,CAAC;AAyBH,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CA2hBzC"}

package/dist/operations/mutation/upsert.js

@@ -15,6 +15,7 @@ import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.j
 import { assertLogicalGroundingClaimKeys, assertSemanticInventoryBoundary, } from "../semantic-advisor/ingestion-boundary.js";
 import { entityContextWarnings } from "./context-warning.js";
 import { buildUpsertCommitGoal, formatUpsertError } from "./contradictions.js";
+import { assertFirmDecisionUnchanged } from "./firm-decision-guard.js";
 import { resolveUpsertOrigin } from "./origin.js";
 import { planRecoveryNotes, settlePendingPlanApplyJournals, withPlanRecoveryNotes, } from "./plan-apply-journal.js";
 import { assertPredicateArgumentVocabulary } from "./predicate-vocabulary-guard.js";
@@ -247,6 +248,7 @@ export async function validateUpsertForCommit(payload, context, options = {}) {
     await assertStoredRequirementBoundary(input, relationships, prolog, staged, lookup);
     await assertLogicalGroundingClaimKeys(prolog, { ...input, relationships }, relationships, staged);
     await assertPredicateArgumentVocabulary(prolog, validated.entity, staged);
+    await assertFirmDecisionUnchanged(payload, context.workspaceRoot, lookup);
     // The origin the write records is added last: none of the checks above
     // reads it, and a rejected payload never pays for the stored-origin read.
     const recorded = await resolveUpsertOrigin(input, prolog, context.clock(), staged, lookup);

package/dist/public/operations/catalog.d.ts

@@ -1125,7 +1125,7 @@ export declare const OPERATION_CATALOG: readonly [{
                     readonly firmness: {
                         readonly type: "string";
                         readonly enum: readonly ["firm", "default", "exploratory"];
-                        readonly 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.";
+                        readonly description: "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.";
                     };
                     readonly rationale: {
                         readonly type: "string";
@@ -1839,7 +1839,7 @@ export declare const OPERATION_CATALOG: readonly [{
                     readonly type: "string";
                     readonly enum: readonly string[];
                 };
-                readonly description: "Optional rule subset. 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. If omitted, server runs canonical and advisory rules plus the full-KB qualityDiagnostics audit scan, including usage telemetry acceptance when evidence exists; migration rules run only when explicitly selected. Advisory and migration findings are non-blocking qualityDiagnostics. If supplied, server preserves scoped validation and skips the full-KB advisory scan.";
+                readonly description: "Optional rule subset. 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, decision-firm-edited, supersedes-reason-missing, supersedes-reason-acknowledged, policy-ownership, policy-markers. If omitted, server runs canonical and advisory rules plus the full-KB qualityDiagnostics audit scan, including usage telemetry acceptance when evidence exists; migration rules run only when explicitly selected. Advisory and migration findings are non-blocking qualityDiagnostics. If supplied, server preserves scoped validation and skips the full-KB advisory scan.";
             };
             readonly sourceFiles: {
                 readonly type: "array";

package/dist/public/operations/decision-firmness.d.ts

@@ -4,11 +4,13 @@ import { type AuthoredEntity } from "./entity-context.js";
 export declare const DECISION_FIRM_UNREFERENCED_RULE = "decision-firm-unreferenced";
 /** Only a firm decision may supersede a firm decision (blocking). */
 export declare const DECISION_FIRM_SUPERSEDED_RULE = "decision-firm-superseded";
+/** A firm decision's claim must not change in place without new human words (blocking). */
+export declare const DECISION_FIRM_EDITED_RULE = "decision-firm-edited";
 /** A supersede must say why under "Why this changed" (blocking). */
 export declare const SUPERSEDES_REASON_MISSING_RULE = "supersedes-reason-missing";
 /** How many legacy supersedes the schema 9 migration acknowledged (info). */
 export declare const SUPERSEDES_REASON_ACKNOWLEDGED_RULE = "supersedes-reason-acknowledged";
-export declare const DECISION_FIRMNESS_RULES: readonly ["decision-firm-unreferenced", "decision-firm-superseded", "supersedes-reason-missing", "supersedes-reason-acknowledged"];
+export declare const DECISION_FIRMNESS_RULES: readonly ["decision-firm-unreferenced", "decision-firm-superseded", "decision-firm-edited", "supersedes-reason-missing", "supersedes-reason-acknowledged"];
 /**
  * The schema version from which a decision without `firmness` reads its
  * firmness from its origin, so a person's or imported rule is firm.
@@ -45,6 +47,14 @@ export declare function evaluateDecisionFirmness(entities: readonly AuthoredEnti
     /** Edges the schema 10 migration recorded (`FROM -> TO`). */
     firmSupersedeAcknowledged?: ReadonlySet<string>;
 }>): Violation[];
+/** Reads a workspace-relative file as committed at HEAD; null when absent. */
+export type CommittedFileReader = (relativePath: string) => string | null;
+/**
+ * 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.
+ */
+export declare function evaluateFirmDecisionEdits(entities: readonly AuthoredEntity[], edges: ReadonlyMap<string, Set<string>>, changed: ReadonlySet<string>, readCommitted: CommittedFileReader): Violation[];
 /** Read the authored decisions once and evaluate the selected rules. */
 export declare function collectDecisionFirmnessViolations(rules: ReadonlySet<string>, workspaceRoot: string): Violation[];
 //# sourceMappingURL=decision-firmness.d.ts.map

package/dist/public/operations/decision-firmness.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decision-firmness.d.ts","sourceRoot":"","sources":["../../../src/public/operations/decision-firmness.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EACL,KAAK,cAAc,EAGpB,MAAM,qBAAqB,CAAC;AAE7B,wEAAwE;AAExE,eAAO,MAAM,+BAA+B,+BAA+B,CAAC;AAC5E,qEAAqE;AAErE,eAAO,MAAM,6BAA6B,6BAA6B,CAAC;AACxE,oEAAoE;AAEpE,eAAO,MAAM,8BAA8B,8BAA8B,CAAC;AAC1E,6EAA6E;AAE7E,eAAO,MAAM,mCAAmC,mCACd,CAAC;AAGnC,eAAO,MAAM,uBAAuB,oIAK1B,CAAC;AAOX;;;GAGG;AAEH,eAAO,MAAM,mCAAmC,KAAK,CAAC;AAiBtD,0CAA0C;AAE1C,wBAAgB,oBAAoB,CAAC,aAAa,EAAE,MAAM,GAAG,cAAc,EAAE,CAS5E;AAED;;;;;GAKG;AAEH,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,SAAS,cAAc,EAAE,GAClC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CA+B1B;AASD;;;;;GAKG;AAEH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,SAAS,cAAc,EAAE,EACnC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,GACtC,cAAc,EAAE,CAQlB;AAED,2EAA2E;AAE3E,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,GACtC,MAAM,EAAE,CAIV;AAED;;;;;GAKG;AAEH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,SAAS,cAAc,EAAE,EACnC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,GACtC,MAAM,EAAE,CAyBV;AAED,uEAAuE;AAEvE,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,SAAS,cAAc,EAAE,EACnC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,EACvC,KAAK,GAAE,WAAW,CAAC,MAAM,CAAoC,EAC7D,YAAY,GAAE,WAAW,CAAC,MAAM,CAAa,EAC7C,OAAO,GAAE,QAAQ,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,6DAA6D;IAC7D,yBAAyB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACjD,CAAM,GACN,SAAS,EAAE,CA+Gb;AAED,wEAAwE;AAExE,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,EAC1B,aAAa,EAAE,MAAM,GACpB,SAAS,EAAE,CAgBb"}
+{"version":3,"file":"decision-firmness.d.ts","sourceRoot":"","sources":["../../../src/public/operations/decision-firmness.ts"],"names":[],"mappings":"AAwCA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EACL,KAAK,cAAc,EAGpB,MAAM,qBAAqB,CAAC;AAE7B,wEAAwE;AAExE,eAAO,MAAM,+BAA+B,+BAA+B,CAAC;AAC5E,qEAAqE;AAErE,eAAO,MAAM,6BAA6B,6BAA6B,CAAC;AACxE,2FAA2F;AAE3F,eAAO,MAAM,yBAAyB,yBAAyB,CAAC;AAChE,oEAAoE;AAEpE,eAAO,MAAM,8BAA8B,8BAA8B,CAAC;AAC1E,6EAA6E;AAE7E,eAAO,MAAM,mCAAmC,mCACd,CAAC;AAGnC,eAAO,MAAM,uBAAuB,4JAM1B,CAAC;AAOX;;;GAGG;AAEH,eAAO,MAAM,mCAAmC,KAAK,CAAC;AAiBtD,0CAA0C;AAE1C,wBAAgB,oBAAoB,CAAC,aAAa,EAAE,MAAM,GAAG,cAAc,EAAE,CAS5E;AAED;;;;;GAKG;AAEH,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,SAAS,cAAc,EAAE,GAClC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CA+B1B;AASD;;;;;GAKG;AAEH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,SAAS,cAAc,EAAE,EACnC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,GACtC,cAAc,EAAE,CAQlB;AAED,2EAA2E;AAE3E,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,GACtC,MAAM,EAAE,CAIV;AAED;;;;;GAKG;AAEH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,SAAS,cAAc,EAAE,EACnC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,GACtC,MAAM,EAAE,CAyBV;AAED,uEAAuE;AAEvE,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,SAAS,cAAc,EAAE,EACnC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,EACvC,KAAK,GAAE,WAAW,CAAC,MAAM,CAAoC,EAC7D,YAAY,GAAE,WAAW,CAAC,MAAM,CAAa,EAC7C,OAAO,GAAE,QAAQ,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,6DAA6D;IAC7D,yBAAyB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACjD,CAAM,GACN,SAAS,EAAE,CA+Gb;AAED,8EAA8E;AAE9E,MAAM,MAAM,mBAAmB,GAAG,CAAC,YAAY,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;AAkC1E;;;;GAIG;AAEH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,SAAS,cAAc,EAAE,EACnC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,EACvC,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,EAC5B,aAAa,EAAE,mBAAmB,GACjC,SAAS,EAAE,CAwBb;AAED,wEAAwE;AAExE,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,EAC1B,aAAa,EAAE,MAAM,GACpB,SAAS,EAAE,CA+Bb"}

package/dist/public/operations/decision-firmness.js

@@ -15,8 +15,10 @@
  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 { execFileSync } from "node:child_process";
 import path from "node:path";
 import { MIN_WHY_CHANGED_WORDS, WHY_THIS_CHANGED_HEADING, carriesFirmness, effectiveFirmness, firmnessIsImplicit, firmnessRef, supersedeAcknowledgement, whyThisChangedWords, } from "../../decision-firmness.js";
+import { firmEditGuidance, unapprovedFirmEdit, } from "../../firm-decision-edit.js";
 import { listLaneMarkdownFiles, readText, } from "../../operations/migration/kb-sources.js";
 import { readAllShards } from "../../relationships/shards.js";
 import { readKbManifest } from "../../utils/kb-manifest.js";
@@ -27,6 +29,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";
@@ -37,6 +42,7 @@ export const SUPERSEDES_REASON_ACKNOWLEDGED_RULE = "supersedes-reason-acknowledg
 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,
 ];
@@ -265,15 +271,82 @@ export function evaluateDecisionFirmness(entities, edges, rules = new Set(DECISI
     }
     return findings;
 }
+/**
+ * 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) {
+    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 = (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, edges, changed, readCommitted) {
+    const superseded = supersededIds(edges);
+    const findings = [];
+    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, workspaceRoot) {
     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/dist/public/operations/specs/check-rules.generated.d.ts

@@ -1,5 +1,5 @@
 /** Every selectable kb_check rule name, registry order. */
 export declare const SELECTABLE_RULE_NAMES: readonly string[];
 /** Comma-separated "Allowed:" fragment for the kb_check rules description. */
-export declare 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";
+export declare 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, decision-firm-edited, supersedes-reason-missing, supersedes-reason-acknowledged, policy-ownership, policy-markers";
 //# sourceMappingURL=check-rules.generated.d.ts.map

package/dist/public/operations/specs/check-rules.generated.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check-rules.generated.d.ts","sourceRoot":"","sources":["../../../../src/public/operations/specs/check-rules.generated.ts"],"names":[],"mappings":"AAUA,2DAA2D;AAC3D,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAqDlD,CAAC;AAGF,8EAA8E;AAC9E,eAAO,MAAM,wBAAwB,gqCAC0nC,CAAC"}
+{"version":3,"file":"check-rules.generated.d.ts","sourceRoot":"","sources":["../../../../src/public/operations/specs/check-rules.generated.ts"],"names":[],"mappings":"AAUA,2DAA2D;AAC3D,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAsDlD,CAAC;AAGF,8EAA8E;AAC9E,eAAO,MAAM,wBAAwB,srCACgpC,CAAC"}

package/dist/public/operations/specs/check-rules.generated.js

@@ -57,6 +57,7 @@ export const SELECTABLE_RULE_NAMES = [
     "entity-context-acknowledged",
     "decision-firm-unreferenced",
     "decision-firm-superseded",
+    "decision-firm-edited",
     "supersedes-reason-missing",
     "supersedes-reason-acknowledged",
     "policy-ownership",
@@ -64,4 +65,4 @@ export const SELECTABLE_RULE_NAMES = [
 ];
 // 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";
+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, decision-firm-edited, supersedes-reason-missing, supersedes-reason-acknowledged, policy-ownership, policy-markers";

package/dist/public/operations/specs/check.d.ts

@@ -12,7 +12,7 @@ export declare const checkSpec: {
                     readonly type: "string";
                     readonly enum: readonly string[];
                 };
-                readonly description: "Optional rule subset. 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. If omitted, server runs canonical and advisory rules plus the full-KB qualityDiagnostics audit scan, including usage telemetry acceptance when evidence exists; migration rules run only when explicitly selected. Advisory and migration findings are non-blocking qualityDiagnostics. If supplied, server preserves scoped validation and skips the full-KB advisory scan.";
+                readonly description: "Optional rule subset. 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, decision-firm-edited, supersedes-reason-missing, supersedes-reason-acknowledged, policy-ownership, policy-markers. If omitted, server runs canonical and advisory rules plus the full-KB qualityDiagnostics audit scan, including usage telemetry acceptance when evidence exists; migration rules run only when explicitly selected. Advisory and migration findings are non-blocking qualityDiagnostics. If supplied, server preserves scoped validation and skips the full-KB advisory scan.";
             };
             readonly sourceFiles: {
                 readonly type: "array";

package/dist/public/operations/specs/mutation-schemas.d.ts

@@ -121,7 +121,7 @@ export declare const ENTITY_PROPERTIES_SCHEMA: {
         readonly firmness: {
             readonly type: "string";
             readonly enum: readonly ["firm", "default", "exploratory"];
-            readonly 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.";
+            readonly description: "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.";
         };
         readonly rationale: {
             readonly type: "string";

package/dist/public/operations/specs/mutation-schemas.js

@@ -105,7 +105,7 @@ export const ENTITY_PROPERTIES_SCHEMA = {
         firmness: {
             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.",
+            description: "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/dist/public/operations/specs/upsert.d.ts

@@ -138,7 +138,7 @@ export declare const upsertSpec: {
                     readonly firmness: {
                         readonly type: "string";
                         readonly enum: readonly ["firm", "default", "exploratory"];
-                        readonly 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.";
+                        readonly description: "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.";
                     };
                     readonly rationale: {
                         readonly type: "string";

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

@@ -2,7 +2,7 @@
 id: kibi-usage
 name: Kibi Usage
 description: Use Kibi's source-first, exact-Git, migration-aware, proof-aware operations safely across MCP or the trusted local CLI, including partial completion repair.
-version: 2.17.0
+version: 2.18.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -368,7 +368,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 +385,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

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

@@ -243,6 +243,11 @@ export declare const GENERATED_RULES: readonly [{
     readonly description: "A requirement or ADR that supersedes a firm decision, retired or not, must itself be firm (and so carry a ref to the human who changed the rule); a default or exploratory replacement cannot overrule a firm decision";
     readonly enforcementClass: "canonical";
     readonly category: "lifecycle";
+}, {
+    readonly name: "decision-firm-edited";
+    readonly description: "A current requirement or ADR that was firm at HEAD must not have its claim (title, stated meaning, the statement its body derives, an ADR's body, or its firmness) changed in place unless the edit cites new human words (a changed origin.ref, or approval_ref on a requirement); supersede it with a firm decision instead";
+    readonly enforcementClass: "canonical";
+    readonly category: "lifecycle";
 }, {
     readonly name: "supersedes-reason-missing";
     readonly description: "A current requirement or ADR that supersedes another must explain why under a 'Why this changed' heading (at least 12 words of prose naming the evidence and answering the old decision's reasoning); supersede edges recorded before schema 9 are acknowledged in the manifest and exempt";

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgXlB,CAAC"}
+{"version":3,"file":"rule-registry.generated.d.ts","sourceRoot":"","sources":["../../src/utils/rule-registry.generated.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuXlB,CAAC"}

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

@@ -301,6 +301,12 @@ export const GENERATED_RULES = [
         enforcementClass: "canonical",
         category: "lifecycle",
     },
+    {
+        name: "decision-firm-edited",
+        description: "A current requirement or ADR that was firm at HEAD must not have its claim (title, stated meaning, the statement its body derives, an ADR's body, or its firmness) changed in place unless the edit cites new human words (a changed origin.ref, or approval_ref on a requirement); supersede it with a firm decision instead",
+        enforcementClass: "canonical",
+        category: "lifecycle",
+    },
     {
         name: "supersedes-reason-missing",
         description: "A current requirement or ADR that supersedes another must explain why under a 'Why this changed' heading (at least 12 words of prose naming the evidence and answering the old decision's reasoning); supersede edges recorded before schema 9 are acknowledged in the manifest and exempt",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cli",
-  "version": "2.24.0",
+  "version": "2.25.0",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {

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/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/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-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.18.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -368,7 +368,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 +385,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