kibi-cli 2.21.0 → 2.22.0

package/dist/public/operations/result-envelope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"result-envelope.d.ts","sourceRoot":"","sources":["../../../src/public/operations/result-envelope.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE7E,eAAO,MAAM,qBAAqB,EAAG,CAAU,CAAC;AAoChD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,UAAU,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAS/B;AAoFD,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAAC;IACtC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC,GAAG,MAAM,CAET;AAYD,wBAAgB,YAAY,CAAC,CAAC,EAC5B,IAAI,EAAE;IACJ,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC,EACD,IAAI,EAAE,CAAC,EACP,OAAO,GAAE,OAAO,CACd,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,QAAQ,GAAG,aAAa,GAAG,aAAa,GAAG,OAAO,CAAC,CACxE,GAAG;IACF;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CACzB,GACL,UAAU,CAAC,CAAC,CAAC,CAmDf;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKrD;AAGD,MAAM,WAAW,uBAAuB;IACtC,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,OAAO,GACd,uBAAuB,CAYzB;AAaD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC3C,IAAI,CAKN"}
+{"version":3,"file":"result-envelope.d.ts","sourceRoot":"","sources":["../../../src/public/operations/result-envelope.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE7E,eAAO,MAAM,qBAAqB,EAAG,CAAU,CAAC;AAkEhD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,UAAU,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAS/B;AAoFD,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAAC;IACtC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC,GAAG,MAAM,CAET;AAYD,wBAAgB,YAAY,CAAC,CAAC,EAC5B,IAAI,EAAE;IACJ,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC,EACD,IAAI,EAAE,CAAC,EACP,OAAO,GAAE,OAAO,CACd,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,QAAQ,GAAG,aAAa,GAAG,aAAa,GAAG,OAAO,CAAC,CACxE,GAAG;IACF;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CACzB,GACL,UAAU,CAAC,CAAC,CAAC,CAsDf;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKrD;AAGD,MAAM,WAAW,uBAAuB;IACtC,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,OAAO,GACd,uBAAuB,CAYzB;AAaD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC3C,IAAI,CAKN"}

package/dist/public/operations/result-envelope.js

@@ -14,6 +14,29 @@ function diagnostics(value) {
         return [entry];
     });
 }
+// Discovery operations whose empty answer may come from an uncompiled store.
+const STORE_READ_OPERATIONS = new Set(["kb_search", "kb_query"]);
+/**
+ * A search or query answered from a branch store that was never compiled
+ * reads an empty KB. The payload already names the store state; the envelope
+ * also raises it as a warning, so a caller that reads only `status` and
+ * `diagnostics` does not take the empty answer as "nothing governs this".
+ */
+// implements REQ-cli-status-pre-first-sync, REQ-mcp-search-discovery
+function uncompiledStoreDiagnostics(operation, row) {
+    const store = row?.branchStore;
+    if (!STORE_READ_OPERATIONS.has(operation) ||
+        !record(store) ||
+        store.state !== "not_compiled")
+        return [];
+    return [
+        {
+            ...(typeof store.code === "string" ? { code: store.code } : {}),
+            severity: "warning",
+            message: `${typeof store.detail === "string" ? `${store.detail} ` : ""}An empty answer here does not mean no requirement governs this; run \`kibi sync\` and ask again.`,
+        },
+    ];
+}
 function nextActions(value) {
     if (!Array.isArray(value))
         return [];
@@ -152,7 +175,10 @@ export function toKibiResult(spec, data, options = {}) {
             ...spec.effects.map((effect) => effectStatus(effect, row, outcome)),
             ...extraFailedEffects(spec.effects, row),
         ],
-        diagnostics: options.diagnostics ?? diagnostics(row?.diagnostics),
+        diagnostics: options.diagnostics ?? [
+            ...diagnostics(row?.diagnostics),
+            ...uncompiledStoreDiagnostics(String(spec.name), row),
+        ],
         nextActions: options.nextActions ?? nextActions(row?.nextActions),
         ...(resultError ? { error: resultError } : {}),
     };

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, 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, 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, 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,EAgDlD,CAAC;AAGF,8EAA8E;AAC9E,eAAO,MAAM,wBAAwB,2hCACq/B,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,EAqDlD,CAAC;AAGF,8EAA8E;AAC9E,eAAO,MAAM,wBAAwB,gqCAC0nC,CAAC"}

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

@@ -12,6 +12,7 @@ export const SELECTABLE_RULE_NAMES = [
     "must-priority-coverage",
     "symbol-coverage",
     "symbol-traceability",
+    "symbol-granularity",
     "no-dangling-refs",
     "source-relationship-parity",
     "branch-store-not-compiled",
@@ -54,9 +55,13 @@ export const SELECTABLE_RULE_NAMES = [
     "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",
 ];
 // 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, 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, 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, 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, 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, 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, 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

@@ -118,6 +118,11 @@ export declare const ENTITY_PROPERTIES_SCHEMA: {
             readonly minLength: 1;
             readonly description: "Requirement-only. Optional reference to the exception's approval decision record.";
         };
+        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 rationale: {
             readonly type: "string";
             readonly minLength: 1;

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

@@ -1 +1 @@
-{"version":3,"file":"mutation-schemas.d.ts","sourceRoot":"","sources":["../../../../src/public/operations/specs/mutation-schemas.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,YAAY,gFASf,CAAC;AAWX,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoX3B,CAAC;AAEX,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;CA8CvB,CAAC"}
+{"version":3,"file":"mutation-schemas.d.ts","sourceRoot":"","sources":["../../../../src/public/operations/specs/mutation-schemas.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,YAAY,gFASf,CAAC;AAWX,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0X3B,CAAC;AAEX,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;CA8CvB,CAAC"}

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

@@ -102,6 +102,11 @@ export const ENTITY_PROPERTIES_SCHEMA = {
             minLength: 1,
             description: "Requirement-only. Optional reference to the exception's approval decision record.",
         },
+        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.",
+        },
         rationale: {
             type: "string",
             minLength: 1,

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

@@ -35,7 +35,7 @@ export declare const validateUpsertSpec: {
 export declare const deleteSpec: {
     readonly name: "kb_delete";
     readonly cliName: "delete";
-    readonly description: "Delete entities by ID. Use only for intentional removals after dependency checks. Do not use as a bulk cleanup shortcut. Side effects: mutates and saves KB; skips entities with dependents.";
+    readonly description: "Delete entities by ID, or exact relationship triples. Use only for intentional removals after dependency checks. Do not use as a bulk cleanup shortcut. An entity authored in a Markdown or YAML source is not deleted directly: the call writes nothing and returns outcome plan_returned with a hash-bound deletionPlan and a nextActions entry holding the exact kb_apply_plan input ({plan, approvedPlanHash}); apply that unmodified, or repeat this call with approvedPlanHash = deletionPlan.planHash to apply the freshly computed plan in one step (a stale or different hash fails with DELETE_PLAN_HASH_MISMATCH and writes nothing). Authored requirements are never deleted: outcome supersession_required points to kb_upsert with a supersedes relationship. dryRun:true previews any delete and writes nothing. Side effects: mutates and saves KB and authored sources; skips entities with dependents; dryRun and plan_returned write nothing.";
     readonly businessInputSchema: {
         readonly type: "object";
         readonly oneOf: readonly [{
@@ -85,7 +85,11 @@ export declare const deleteSpec: {
             readonly approvedPlanHash: {
                 readonly type: "string";
                 readonly pattern: "^[a-fA-F0-9]{64}$";
-                readonly description: "Exact hash returned by a prior authored-entity deletion plan.";
+                readonly description: "With ids only: the deletionPlan.planHash a prior call for the same ids returned. The plan is recomputed and applied through kb_apply_plan when its hash still matches; a mismatch fails with DELETE_PLAN_HASH_MISMATCH and writes nothing. Not allowed with relationships or dryRun.";
+            };
+            readonly dryRun: {
+                readonly type: "boolean";
+                readonly description: "Preview without writing. Relationship and direct entity deletes run their preflight and return outcome dry_run with wouldDelete counts, the sourceWrites (paths and hashes) a commit would make, and skippedEffects. Authored ids return the same deletion plan as without dryRun.";
             };
         };
     };

package/dist/public/operations/specs/mutation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mutation.d.ts","sourceRoot":"","sources":["../../../../src/public/operations/specs/mutation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAC;AAOvE,OAAO,EAAE,qBAAqB,EAAE,MAAM,iDAAiD,CAAC;AAIxF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsBuC,CAAC;AAEvE,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6CuC,CAAC"}
+{"version":3,"file":"mutation.d.ts","sourceRoot":"","sources":["../../../../src/public/operations/specs/mutation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAC;AAOvE,OAAO,EAAE,qBAAqB,EAAE,MAAM,iDAAiD,CAAC;AAIxF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsBuC,CAAC;AAEvE,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkDuC,CAAC"}

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

@@ -26,7 +26,7 @@ export const validateUpsertSpec = {
 export const deleteSpec = {
     name: "kb_delete",
     cliName: "delete",
-    description: "Delete entities by ID. Use only for intentional removals after dependency checks. Do not use as a bulk cleanup shortcut. Side effects: mutates and saves KB; skips entities with dependents.",
+    description: "Delete entities by ID, or exact relationship triples. Use only for intentional removals after dependency checks. Do not use as a bulk cleanup shortcut. An entity authored in a Markdown or YAML source is not deleted directly: the call writes nothing and returns outcome plan_returned with a hash-bound deletionPlan and a nextActions entry holding the exact kb_apply_plan input ({plan, approvedPlanHash}); apply that unmodified, or repeat this call with approvedPlanHash = deletionPlan.planHash to apply the freshly computed plan in one step (a stale or different hash fails with DELETE_PLAN_HASH_MISMATCH and writes nothing). Authored requirements are never deleted: outcome supersession_required points to kb_upsert with a supersedes relationship. dryRun:true previews any delete and writes nothing. Side effects: mutates and saves KB and authored sources; skips entities with dependents; dryRun and plan_returned write nothing.",
     businessInputSchema: {
         type: "object",
         oneOf: [
@@ -58,7 +58,11 @@ export const deleteSpec = {
             approvedPlanHash: {
                 type: "string",
                 pattern: "^[a-fA-F0-9]{64}$",
-                description: "Exact hash returned by a prior authored-entity deletion plan.",
+                description: "With ids only: the deletionPlan.planHash a prior call for the same ids returned. The plan is recomputed and applied through kb_apply_plan when its hash still matches; a mismatch fails with DELETE_PLAN_HASH_MISMATCH and writes nothing. Not allowed with relationships or dryRun.",
+            },
+            dryRun: {
+                type: "boolean",
+                description: "Preview without writing. Relationship and direct entity deletes run their preflight and return outcome dry_run with wouldDelete counts, the sourceWrites (paths and hashes) a commit would make, and skippedEffects. Authored ids return the same deletion plan as without dryRun.",
             },
         },
     },

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

@@ -270,7 +270,7 @@ export declare const applyPlanSpec: {
             readonly plan: {
                 readonly type: "object";
                 readonly required: readonly ["version", "planHash"];
-                readonly description: "The complete kibi.bootstrap-plan.v1, kibi.compile-plan.v1, kibi.migration-plan.v2, or hash-bound kibi.entity-deletion-plan.v1 object. Migration plans require approvedActionIds and reject blocked/non-automatic actions.";
+                readonly description: "The complete kibi.bootstrap-plan.v1, kibi.compile-plan.v1, kibi.migration-plan.v2, or hash-bound kibi.entity-deletion-plan.v1 object. Migration plans require approvedActionIds and reject blocked actions and review actions Kibi cannot execute.";
             };
             readonly approvedActionIds: {
                 readonly type: "array";
@@ -278,7 +278,7 @@ export declare const applyPlanSpec: {
                     readonly type: "string";
                     readonly minLength: 1;
                 };
-                readonly description: "Required for migration-plan.v2. Exact automatic action IDs explicitly approved for this application.";
+                readonly description: "Required for migration-plan.v2. Exact action IDs explicitly approved for this application: automatic actions, or review actions with a cli invocation that Kibi executes only when approved by id (for example semantic_inventory_rederive_drop_grounding).";
             };
             readonly recoveryJournalId: {
                 readonly type: "string";

package/dist/public/operations/specs/planning.js

@@ -188,12 +188,12 @@ export const applyPlanSpec = {
             plan: {
                 type: "object",
                 required: ["version", "planHash"],
-                description: "The complete kibi.bootstrap-plan.v1, kibi.compile-plan.v1, kibi.migration-plan.v2, or hash-bound kibi.entity-deletion-plan.v1 object. Migration plans require approvedActionIds and reject blocked/non-automatic actions.",
+                description: "The complete kibi.bootstrap-plan.v1, kibi.compile-plan.v1, kibi.migration-plan.v2, or hash-bound kibi.entity-deletion-plan.v1 object. Migration plans require approvedActionIds and reject blocked actions and review actions Kibi cannot execute.",
             },
             approvedActionIds: {
                 type: "array",
                 items: { type: "string", minLength: 1 },
-                description: "Required for migration-plan.v2. Exact automatic action IDs explicitly approved for this application.",
+                description: "Required for migration-plan.v2. Exact action IDs explicitly approved for this application: automatic actions, or review actions with a cli invocation that Kibi executes only when approved by id (for example semantic_inventory_rederive_drop_grounding).",
             },
             recoveryJournalId: {
                 type: "string",

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

@@ -135,6 +135,11 @@ export declare const upsertSpec: {
                         readonly minLength: 1;
                         readonly description: "Requirement-only. Optional reference to the exception's approval decision record.";
                     };
+                    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 rationale: {
                         readonly type: "string";
                         readonly minLength: 1;

package/dist/public/operations/specs/upsert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upsert.d.ts","sourceRoot":"","sources":["../../../../src/public/operations/specs/upsert.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAC;AAQvE,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0DuC,CAAC"}
+{"version":3,"file":"upsert.d.ts","sourceRoot":"","sources":["../../../../src/public/operations/specs/upsert.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAC;AAQvE,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0DuC,CAAC"}

package/dist/public/operations/symbol-granularity-check.d.ts

@@ -0,0 +1,18 @@
+import type { Violation } from "../../utils/rule-registry.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.
+ */
+export declare const SYMBOL_GRANULARITY_RULE = "symbol-granularity";
+/**
+ * `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.
+ */
+export declare function collectSymbolGranularityViolations(prolog: Pick<PrologPort, "query">, workspaceRoot: string, rules: ReadonlySet<string>): Promise<Violation[]>;
+//# sourceMappingURL=symbol-granularity-check.d.ts.map

package/dist/public/operations/symbol-granularity-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-granularity-check.d.ts","sourceRoot":"","sources":["../../../src/public/operations/symbol-granularity-check.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAQ9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;GAKG;AAEH,eAAO,MAAM,uBAAuB,uBAAuB,CAAC;AA+J5D;;;;;;GAMG;AAEH,wBAAsB,kCAAkC,CACtD,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,EACjC,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,GACzB,OAAO,CAAC,SAAS,EAAE,CAAC,CAYtB"}

package/dist/public/operations/symbol-granularity-check.js

@@ -0,0 +1,175 @@
+/*
+ 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 { createMaintenanceSourceAnalysisService } from "../../plugins/maintenance-source-analysis.js";
+import { normalizeEntityId, parseEntityFromList, parseListOfLists, parseTriples, } from "../../prolog/codec.js";
+import { extractSymbolsFromStagedFileAsync, } from "../../traceability/symbol-extract.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";
+/**
+ * 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, key) {
+    const value = entity[key];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+// implements REQ-cli-check
+async function loadSymbolResults(prolog, workspaceRoot) {
+    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();
+    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 = [];
+    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) {
+    return results.filter((result) => result.relationships.some((relationship) => isTraceabilityRelationshipType(relationship.type)) && !isAllowedGranularityReason(result.entity.granularity_reason));
+}
+function readRegularFile(absolutePath) {
+    try {
+        if (!statSync(absolutePath).isFile())
+            return null;
+        return readFileSync(absolutePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+// implements REQ-cli-check
+async function analyzeFiles(files, results, workspaceRoot) {
+    const manifestLookup = createImpactManifestLookup(results);
+    const service = createMaintenanceSourceAnalysisService(workspaceRoot);
+    const analyses = new Map();
+    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, sourceSymbolsByFile, workspaceRoot) {
+    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, workspaceRoot, rules) {
+    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/dist/public/schemas/entity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../../src/public/schemas/entity.ts"],"names":[],"mappings":"AAwTA,QAAA,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CA4ZzC,CAAC;AAEF,eAAe,YAAY,CAAC"}
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../../src/public/schemas/entity.ts"],"names":[],"mappings":"AAwTA,QAAA,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAwazC,CAAC;AAEF,eAAe,YAAY,CAAC"}

package/dist/public/schemas/entity.js

@@ -333,6 +333,11 @@ const entitySchema = {
         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"],
@@ -680,6 +685,12 @@ const entitySchema = {
                 },
             },
         },
+        {
+            if: {
+                properties: { type: { enum: ["req", "adr"] } },
+            },
+            else: { not: { required: ["firmness"] } },
+        },
         {
             if: {
                 properties: { type: { const: "scenario" } },

package/dist/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/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.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/dist/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