kibi-cli 2.29.0 → 2.31.0

package/dist/operations/mutation/validate-upsert.js

@@ -1,13 +1,13 @@
 // implements REQ-kibi-operation-interface-parity
+import { codedErrorOf } from "../../cli-errors.js";
 import { escapeAtom } from "../../prolog/codec.js";
-import { loadEntities } from "../../public/operations/discovery-entities.js";
 import { entityIdStyleWarnings } from "../../utils/entity-id-style.js";
 import { entityContextWarnings } from "./context-warning.js";
 import { buildUpsertContradictionPreviewGoal, buildWhatIfAnalysisGoal, formatUpsertError, } from "./contradictions.js";
 import { validateRelationshipSources } from "./relationships.js";
-import { canonicalSourcePath } from "./source-authoring.js";
+import { canonicalSourcePath, renderSourceWrite } from "./source-authoring.js";
 import { validateSymbolGranularity } from "./symbol-granularity.js";
-import { analyzeUpsertSemantics, validateAppendOnlyProofReceipts, validateUpsertForCommit, } from "./upsert.js";
+import { analyzeUpsertSemantics, sourceWriteScope, validateAppendOnlyProofReceipts, validateUpsertForCommit, } from "./upsert.js";
 import { validateUpsertInput } from "./validation.js";
 import { symbolCoverageWarnings } from "./warnings.js";
 import { isBlockingWitness, parseWhatIfAnalysis } from "./what-if.js";
@@ -18,49 +18,53 @@ async function entityExists(prolog, id) {
 }
 // implements REQ-kibi-operation-interface-parity, REQ-kb-entity-body-context
 /**
- * The authored document a real kb_upsert would update, resolved with the
- * write's own rules (stored authored source, else the canonical lane path).
- * The preview entity's `source` is the runtime marker, so without this the
- * context warning would judge the statement instead of the existing body the
- * write preserves. Undefined when the write would not touch a document.
+ * The authored document a real kb_upsert would update, resolved and rendered
+ * with the write's own rules (sourceWriteScope and renderSourceWrite) but
+ * never written. A path or format the write would refuse
+ * (DOCUMENT_PATH_REQUIRED, SOURCE_PATH_INVALID, SOURCE_FORMAT_UNSUPPORTED)
+ * throws the write's own error. The preview entity's `source` is the runtime
+ * marker, so the returned path lets the context warning judge the existing
+ * body the write preserves. Undefined when the write would not touch a
+ * document.
  */
-async function previewDocumentPath(input, entity, context) {
-    if (context.fs === undefined || context.sourceFirst === false) {
+async function previewSourceWrite(input, entity, context) {
+    const fs = context.fs;
+    if (fs === undefined || context.sourceFirst === false)
         return undefined;
-    }
-    try {
-        const existing = context.prolog === undefined
-            ? undefined
-            : (await loadEntities(context.prolog, {
-                id: input.id,
-                type: input.type,
-            }))[0];
-        const existingSource = typeof existing?.source === "string" ? existing.source : undefined;
-        if (input.document === undefined &&
-            existing !== undefined &&
-            !existingSource?.match(/\.(?:md|mdx|ya?ml|json)$/i)) {
+    if (context.prolog === undefined) {
+        // No store, so no write either: only locate the document for the
+        // context warning.
+        try {
+            return canonicalSourcePath(context, input, entity);
+        }
+        catch {
             return undefined;
         }
-        return canonicalSourcePath(context, input, entity, existing);
     }
-    catch {
+    const scope = await sourceWriteScope(input, context);
+    if (scope === null)
         return undefined;
-    }
+    const { relative } = await renderSourceWrite(input, entity, scope.existing, {
+        ...context,
+        fs,
+    });
+    return relative;
 }
 // implements REQ-kibi-operation-interface-parity, REQ-kibi-truthful-consistency
 /**
- * The commit-time contradiction check, run against a staged and rolled-back
- * copy of the store. Only a `req` commit runs it (facts and scenarios never
- * do), and `_skipContradictionCheck` skips it at commit, so the preview skips
- * it too. A refusal carries the same message the commit would raise.
+ * The commit goal's own refusal rules, run against a staged and rolled-back
+ * copy of the store for every entity type: a relationship whose endpoint
+ * does not exist, an invalid relationship direction, a symbol mixing
+ * executable_for with implements/covered_by, and the requirement
+ * contradiction check (only a `req` commit runs it, and
+ * `_skipContradictionCheck` skips it at commit and here alike). A refusal
+ * carries the same message the commit would raise.
  */
-async function previewContradictions(prolog, input, entity, relationships) {
-    if (input.type !== "req" || input._skipContradictionCheck === true)
-        return;
+async function previewCommit(prolog, input, entity, relationships) {
     const preview = await prolog.query(buildUpsertContradictionPreviewGoal({
         entity,
         relationships,
-        skipContradictionCheck: false,
+        skipContradictionCheck: input._skipContradictionCheck === true,
     }));
     if (!preview.success) {
         throw new Error(formatUpsertError(input.id, preview.error, preview.errorRecord));
@@ -167,6 +171,12 @@ async function validateWithoutStore(input, context) {
     });
     return { entity: validated.entity, semantic };
 }
+function isModuleLoadFailure(error) {
+    if (!(error instanceof Error))
+        return false;
+    const code = error.code;
+    return code === "MODULE_NOT_FOUND" || code === "ERR_MODULE_NOT_FOUND";
+}
 // implements REQ-kibi-operation-interface-parity, REQ-kibi-truthful-consistency
 /**
  * kb_upsert dryRun:true (and the former kb_validate_upsert preflight). With a
@@ -181,14 +191,20 @@ export async function executeValidateUpsert(input, context) {
         let whatIf;
         let stagedFacts;
         let relationships = input.relationships ?? [];
+        let targetPath;
         const { entity, semantic } = context.prolog !== undefined
             ? await stagePlannedFacts(input, context).then(async (facts) => {
                 const result = await validateUpsertForCommit(input, context, facts === null ? {} : { staged: facts.staged });
-                // The commit goal checks requirement contradictions after the
-                // validations above; a dry run previews that stage as well, so
+                // The write publishes the authored document before its commit
+                // goal; render it (without writing) in the same order, so a
+                // source refusal surfaces here exactly as the write raises it.
+                targetPath = await previewSourceWrite(input, result.validated.entity, context);
+                // The commit goal refuses missing relationship endpoints, mixed
+                // symbol roles and requirement contradictions after the
+                // validations above; a dry run previews that goal as well, so
                 // "valid" means the commit would not refuse the write.
                 if (facts === null) {
-                    await previewContradictions(context.prolog, input, result.validated.entity, result.validated.relationships);
+                    await previewCommit(context.prolog, input, result.validated.entity, result.validated.relationships);
                 }
                 else {
                     stagedFacts = [...facts.staged.entities.keys()];
@@ -201,6 +217,8 @@ export async function executeValidateUpsert(input, context) {
                 };
             })
             : await validateWithoutStore(input, context);
+        if (context.prolog === undefined)
+            targetPath = await previewSourceWrite(input, entity, context);
         // Style warnings apply only to entities this upsert would create, so the
         // existence read happens only when the ID actually has a style issue.
         const candidateIdStyleWarnings = entityIdStyleWarnings({
@@ -225,7 +243,7 @@ export async function executeValidateUpsert(input, context) {
                 ...coverageWarnings,
                 ...idStyleWarnings,
                 ...entityContextWarnings(input, entity, context.workspaceRoot, {
-                    targetPath: await previewDocumentPath(input, entity, context),
+                    targetPath,
                 }),
             ],
             semanticAdvisor: semantic.receipt,
@@ -247,13 +265,19 @@ export async function executeValidateUpsert(input, context) {
         };
     }
     catch (error) {
+        // A module that fails to load is a broken installation, not a property of
+        // the payload: report it as a tool failure instead of an invalid payload.
+        if (isModuleLoadFailure(error))
+            throw error;
         const message = error instanceof Error ? error.message : String(error);
+        const errorCode = codedErrorOf(error)?.code;
         const payload = {
             valid: false,
             errors: [message],
             warnings: [],
             semanticAdvisor: null,
             normalizedPreview: null,
+            ...(errorCode !== undefined ? { errorCode } : {}),
         };
         return {
             content: [

package/dist/operations/planning/apply-plan.js

@@ -2265,13 +2265,13 @@ async function applyMigrationPlan(args, context, onCommitted = () => undefined)
             : finalStatus.proofSnapshotDirty === false
                 ? "fresh"
                 : "not_evaluated";
-    const proven = coverageSummary?.proofProven;
+    const tested = coverageSummary?.proofTested;
     const missing = coverageSummary?.proofMissing;
-    const proofState = typeof proven !== "number" || typeof missing !== "number"
+    const proofState = typeof tested !== "number" || typeof missing !== "number"
         ? "not_evaluated"
-        : proven > 0 && missing === 0
-            ? "proven"
-            : proven > 0
+        : tested > 0 && missing === 0
+            ? "tested"
+            : tested > 0
                 ? "mixed"
                 : "unresolved";
     const payload = {

package/dist/operations/proof/baseline-diff.d.ts

@@ -1,4 +1,4 @@
-export declare const PROOF_BASELINE_VERSION = "kibi.proof-baseline.v2";
+export declare const PROOF_BASELINE_VERSION = "kibi.proof-baseline.v3";
 export type RequirementFingerprint = {
     readonly proofStatus: string;
     readonly gaps: readonly string[];

package/dist/operations/proof/baseline-diff.js

@@ -8,7 +8,7 @@
  (at your option) any later version.
  */
 // implements REQ-kibi-verification-evidence-contract
-export const PROOF_BASELINE_VERSION = "kibi.proof-baseline.v2";
+export const PROOF_BASELINE_VERSION = "kibi.proof-baseline.v3";
 function asStringArray(value) {
     if (!Array.isArray(value))
         return [];

package/dist/operations/proof/impact.d.ts

@@ -5,8 +5,8 @@ export type ProofBaselineFile = {
     readonly version?: string;
     readonly mode?: string;
     readonly currentRequirements?: number;
-    readonly proofProven?: number;
-    readonly currentUnproven?: number;
+    readonly proofTested?: number;
+    readonly currentUntested?: number;
     readonly trackedGaps?: Record<string, number>;
     readonly requirements?: RequirementFingerprints;
 };
@@ -14,8 +14,8 @@ export type ProofImpactResult = {
     readonly comparisonTarget: typeof COMMITTED_BASELINE_PATH;
     readonly baselineVersion: string;
     readonly currentRequirements: number;
-    readonly proofProven: number;
-    readonly currentUnproven: number;
+    readonly proofTested: number;
+    readonly currentUntested: number;
     readonly changes: ReturnType<typeof diffFingerprints>;
 };
 export type ReadCommittedFile = (workspaceRoot: string, relativePath: string) => string | Promise<string>;
@@ -27,6 +27,12 @@ export type ProofImpactExecuteOptions = {
 };
 export declare function readCommittedHeadFile(workspaceRoot: string, relativePath: string): string;
 export declare function loadCommittedBaseline(workspaceRoot: string, readCommittedFile?: ReadCommittedFile): Promise<ProofBaselineFile>;
+/**
+ * A baseline committed before kibi.proof-baseline.v3 records a fully tested
+ * requirement as `proven`. Read it as `tested`, so the comparison shows real
+ * changes instead of a rename on every row.
+ */
+export declare function upgradeBaselineStatuses(baseline: ProofBaselineFile): ProofBaselineFile;
 /** Diagnostic only: successful evaluation always exits 0. Ratchet lives in check-proof-baseline.mjs. */
 export declare function proofImpactExitCode(_result: ProofImpactResult): 0;
 export declare function buildProofImpact(baseline: ProofBaselineFile, coverage: {

package/dist/operations/proof/impact.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"impact.d.ts","sourceRoot":"","sources":["../../../src/operations/proof/impact.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAEjF,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,gBAAgB,EAGjB,MAAM,oBAAoB,CAAC;AAG5B,eAAO,MAAM,uBAAuB,wBAAwB,CAAC;AAE7D,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9C,QAAQ,CAAC,YAAY,CAAC,EAAE,uBAAuB,CAAC;CACjD,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,uBAAuB,CAAC;IAC1D,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;CACvD,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,CAC9B,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,KACjB,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAE9B,MAAM,MAAM,yBAAyB,GAAG;IACtC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAC/C,QAAQ,CAAC,YAAY,CAAC,EAAE,CACtB,OAAO,EAAE,gBAAgB,KACtB,OAAO,CAAC;QAAE,iBAAiB,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAC9C,CAAC;AAgDF,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,GACnB,MAAM,CAcR;AAGD,wBAAsB,qBAAqB,CACzC,aAAa,EAAE,MAAM,EACrB,iBAAiB,GAAE,iBAAyC,GAC3D,OAAO,CAAC,iBAAiB,CAAC,CAS5B;AAED,wGAAwG;AACxG,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,iBAAiB,GAAG,CAAC,CAEjE;AAGD,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,iBAAiB,EAC3B,QAAQ,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GAC9D;IAAE,MAAM,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,eAAe,EAAE,CAAA;CAAE,CAuBxD;AAGD,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,iBAAiB,EACzB,IAAI,EAAE,SAAS,eAAe,EAAE,GAC/B,MAAM,CAYR;AAGD,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC;IACT,MAAM,EAAE,iBAAiB,CAAC;IAC1B,IAAI,EAAE,eAAe,EAAE,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC,CAmBD"}
+{"version":3,"file":"impact.d.ts","sourceRoot":"","sources":["../../../src/operations/proof/impact.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAEjF,OAAO,EACL,KAAK,eAAe,EAEpB,KAAK,uBAAuB,EAC5B,gBAAgB,EAGjB,MAAM,oBAAoB,CAAC;AAG5B,eAAO,MAAM,uBAAuB,wBAAwB,CAAC;AAE7D,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9C,QAAQ,CAAC,YAAY,CAAC,EAAE,uBAAuB,CAAC;CACjD,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,uBAAuB,CAAC;IAC1D,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;CACvD,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,CAC9B,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,KACjB,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAE9B,MAAM,MAAM,yBAAyB,GAAG;IACtC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAC/C,QAAQ,CAAC,YAAY,CAAC,EAAE,CACtB,OAAO,EAAE,gBAAgB,KACtB,OAAO,CAAC;QAAE,iBAAiB,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAC9C,CAAC;AAgDF,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,GACnB,MAAM,CAcR;AAGD,wBAAsB,qBAAqB,CACzC,aAAa,EAAE,MAAM,EACrB,iBAAiB,GAAE,iBAAyC,GAC3D,OAAO,CAAC,iBAAiB,CAAC,CAW5B;AAED;;;;GAIG;AAEH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,iBAAiB,GAC1B,iBAAiB,CAUnB;AAED,wGAAwG;AACxG,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,iBAAiB,GAAG,CAAC,CAEjE;AAGD,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,iBAAiB,EAC3B,QAAQ,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GAC9D;IAAE,MAAM,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,eAAe,EAAE,CAAA;CAAE,CAuBxD;AAGD,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,iBAAiB,EACzB,IAAI,EAAE,SAAS,eAAe,EAAE,GAC/B,MAAM,CAYR;AAGD,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC;IACT,MAAM,EAAE,iBAAiB,CAAC;IAC1B,IAAI,EAAE,eAAe,EAAE,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC,CAmBD"}

package/dist/operations/proof/impact.js

@@ -58,12 +58,32 @@ export function readCommittedHeadFile(workspaceRoot, relativePath) {
 // implements REQ-kibi-verification-evidence-contract
 export async function loadCommittedBaseline(workspaceRoot, readCommittedFile = readCommittedHeadFile) {
     const raw = await readCommittedFile(workspaceRoot, COMMITTED_BASELINE_PATH);
+    let parsed;
     try {
-        return JSON.parse(raw);
+        parsed = JSON.parse(raw);
     }
     catch {
         throw new Error(`proof impact: HEAD:${COMMITTED_BASELINE_PATH} is not valid JSON`);
     }
+    return upgradeBaselineStatuses(parsed);
+}
+/**
+ * A baseline committed before kibi.proof-baseline.v3 records a fully tested
+ * requirement as `proven`. Read it as `tested`, so the comparison shows real
+ * changes instead of a rename on every row.
+ */
+// implements REQ-kibi-evidence-levels
+export function upgradeBaselineStatuses(baseline) {
+    if (baseline.requirements === undefined)
+        return baseline;
+    const requirements = {};
+    for (const [id, entry] of Object.entries(baseline.requirements)) {
+        requirements[id] =
+            entry?.proofStatus === "proven"
+                ? { ...entry, proofStatus: "tested" }
+                : entry;
+    }
+    return { ...baseline, requirements };
 }
 /** Diagnostic only: successful evaluation always exits 0. Ratchet lives in check-proof-baseline.mjs. */
 export function proofImpactExitCode(_result) {
@@ -77,8 +97,8 @@ export function buildProofImpact(baseline, coverage) {
     const summary = coverage.summary ?? {};
     const proofNotApplicable = asNumber(summary.proofNotApplicable);
     const total = asNumber(summary.total);
-    const proofProven = asNumber(summary.proofProven);
-    const currentUnproven = asNumber(summary.proofMissing) + asNumber(summary.proofUnresolved);
+    const proofTested = asNumber(summary.proofTested);
+    const currentUntested = asNumber(summary.proofMissing) + asNumber(summary.proofUnresolved);
     const current = fingerprintRequirements(rows);
     const changes = diffFingerprints(baseline.requirements, current);
     return {
@@ -87,8 +107,8 @@ export function buildProofImpact(baseline, coverage) {
             comparisonTarget: COMMITTED_BASELINE_PATH,
             baselineVersion: baseline.version ?? "unknown",
             currentRequirements: total - proofNotApplicable,
-            proofProven,
-            currentUnproven,
+            proofTested,
+            currentUntested,
             changes,
         },
     };
@@ -99,8 +119,8 @@ export function renderProofImpact(result, rows) {
         `Proof impact compared to committed ${result.comparisonTarget}`,
         `baseline version: ${result.baselineVersion}`,
         `current requirements: ${result.currentRequirements}`,
-        `proofProven: ${result.proofProven}`,
-        `currentUnproven: ${result.currentUnproven}`,
+        `proofTested: ${result.proofTested}`,
+        `currentUntested: ${result.currentUntested}`,
         `changed requirements: ${result.changes.length}`,
         "",
     ];

package/dist/public/diagnostic-usage.js

@@ -103,7 +103,7 @@ function appendCoverageFields(fields, args, result) {
     const scope = isRecord(repairPlan?.scope) ? repairPlan.scope : undefined;
     fields.coverage_by = typeof args.by === "string" ? args.by : "req";
     fields.coverage_requirement_count = Number(summary.total ?? rows.length);
-    fields.coverage_proven_count = Number(summary.proofProven ?? 0);
+    fields.coverage_tested_count = Number(summary.proofTested ?? 0);
     fields.coverage_proof_missing_count = Number(summary.proofMissing ?? 0);
     fields.coverage_proof_gap_count = gapCodes.length;
     fields.coverage_gap_codes = [...new Set(gapCodes)].sort();
@@ -160,7 +160,7 @@ export function deriveDiagnosticUsageFields(tool, args, telemetry, result) {
     }
     if (tool === "kb_coverage" && structured) {
         appendCoverageFields(fields, args, structured);
-        fields.result_summary = `${String(fields.coverage_proven_count)} proven; ${String(fields.coverage_proof_gap_count)} proof gaps`;
+        fields.result_summary = `${String(fields.coverage_tested_count)} tested; ${String(fields.coverage_proof_gap_count)} proof gaps`;
     }
     if (tool === "kb_semantic_advisor" && structured) {
         appendSemanticFields(fields, structured.receipt);

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

@@ -308,7 +308,7 @@ export declare const OPERATION_CATALOG: readonly [{
 }, {
     readonly name: "kb_status";
     readonly cliName: "status";
-    readonly description: "Report current branch, KB snapshot, freshness metadata, schema status, and a typed kibi.migration-plan.v2 action graph. Read-only status inspection with no mutation side effects; damaged stores are diagnosed without starting the engine.";
+    readonly description: "Report current branch, KB snapshot, freshness metadata, schema status, and a typed kibi.migration-plan.v2 action graph. Call it first to orient on a branch or after a failed call; use kb_check for validation findings and kb_coverage for proof status. Read-only status inspection with no mutation side effects; damaged stores are diagnosed without starting the engine.";
     readonly businessInputSchema: {
         readonly type: "object";
         readonly properties: {};
@@ -320,42 +320,49 @@ export declare const OPERATION_CATALOG: readonly [{
 }, {
     readonly name: "kb_find_gaps";
     readonly cliName: "find-gaps";
-    readonly description: "Run bulk missing/present relationship analysis over KB entities. Use for questions like which requirements lack scenarios or tests. No mutation side effects.";
+    readonly description: "List KB entities by the relationships they lack or have. Use for questions like which requirements lack scenarios or tests; all filters must match, and a relationship counts in either direction. Use kb_coverage instead for proof status and repair plans, and kb_check for rule violations. No mutation side effects.";
     readonly businessInputSchema: {
         readonly type: "object";
         readonly properties: {
             readonly type: {
                 readonly type: "string";
                 readonly enum: readonly ["req", "scenario", "test", "adr", "flag", "event", "symbol", "fact"];
+                readonly description: "Only report entities of this type. Omit for all types.";
             };
             readonly missingRelationships: {
                 readonly type: "array";
                 readonly items: {
                     readonly type: "string";
                 };
+                readonly description: "Relationship types the entity must have none of, in either direction, for example specified_by or verified_by. verified_by and validates satisfy each other.";
             };
             readonly presentRelationships: {
                 readonly type: "array";
                 readonly items: {
                     readonly type: "string";
                 };
+                readonly description: "Relationship types the entity must have at least one of each, in either direction.";
             };
             readonly tags: {
                 readonly type: "array";
                 readonly items: {
                     readonly type: "string";
                 };
+                readonly description: "Keep entities carrying any of these metadata tags. Bootstrap provenance stubs appear in rows only when this names bootstrap:provenance-stub.";
             };
             readonly sourceFile: {
                 readonly type: "string";
+                readonly description: "Keep entities whose source path contains this substring.";
             };
             readonly limit: {
                 readonly type: "integer";
                 readonly default: 100;
+                readonly description: "Maximum rows to return; count reports the full total.";
             };
             readonly offset: {
                 readonly type: "integer";
                 readonly default: 0;
+                readonly description: "Zero-based row offset for pagination.";
             };
         };
     };
@@ -365,7 +372,7 @@ export declare const OPERATION_CATALOG: readonly [{
 }, {
     readonly name: "kb_coverage";
     readonly cliName: "coverage";
-    readonly description: "Generate curated structural coverage and conservative end-to-end requirement proof reports for requirements, symbols, or grouped types. Reports include the compatible repair plan plus typed kibi.migration-plan.v2 actions; semantic and E2E actions remain review/execution work. Paginated plans identify incomplete scope and no mutation occurs.";
+    readonly description: "Generate curated structural coverage and conservative end-to-end requirement proof reports for requirements, symbols, or grouped types. Use it to ask which requirements are tested end to end, how strong each requirement's evidence is (evidenceLevel: proved, tested, asserted or unverified), and what blocks the rest; use kb_find_gaps for a plain list of missing links and kb_check for rule violations. Reports include the compatible repair plan plus typed kibi.migration-plan.v2 actions; semantic and E2E actions remain review/execution work. Paginated plans identify incomplete scope and no mutation occurs.";
     readonly businessInputSchema: {
         readonly type: "object";
         readonly properties: {
@@ -373,36 +380,42 @@ export declare const OPERATION_CATALOG: readonly [{
                 readonly type: "string";
                 readonly enum: readonly ["req", "symbol", "type"];
                 readonly default: "req";
+                readonly description: "Report shape: req gives per-requirement proof status and a repair plan, symbol gives per-symbol ownership coverage, type gives counts per entity type.";
             };
             readonly tags: {
                 readonly type: "array";
                 readonly items: {
                     readonly type: "string";
                 };
+                readonly description: "Keep rows for entities carrying any of these metadata tags.";
             };
             readonly includePassing: {
                 readonly type: "boolean";
                 readonly default: false;
+                readonly description: "Also return rows that are already tested or not applicable. By default only rows that still need repair are returned.";
             };
             readonly statuses: {
                 readonly type: "array";
                 readonly items: {
                     readonly type: "string";
-                    readonly enum: readonly ["proven", "missing", "unresolved", "not_applicable"];
+                    readonly enum: readonly ["tested", "missing", "unresolved", "not_applicable"];
                 };
                 readonly description: "Requirement proof-status filter (req mode): include only rows whose proofStatus is listed. Selecting statuses implies include-passing; not_applicable rows carry their typed applicability reason in proofStages.applicability.reason. The summary always reflects the whole KB.";
             };
             readonly includeTransitive: {
                 readonly type: "boolean";
                 readonly default: true;
+                readonly description: "Count symbol coverage reached transitively through linked entities, not only direct links.";
             };
             readonly limit: {
                 readonly type: "integer";
                 readonly default: 100;
+                readonly description: "Maximum rows to return. When the repair plan reports scope.complete false, rerun with offset 0 and a larger limit.";
             };
             readonly offset: {
                 readonly type: "integer";
                 readonly default: 0;
+                readonly description: "Zero-based row offset for pagination.";
             };
             readonly includeMigrationPreview: {
                 readonly type: "boolean";
@@ -444,7 +457,7 @@ export declare const OPERATION_CATALOG: readonly [{
 }, {
     readonly name: "kb_graph";
     readonly cliName: "graph";
-    readonly description: "Run bounded graph traversal from one or more seed IDs across curated relationship types. No mutation side effects.";
+    readonly description: "Run bounded graph traversal from one or more seed IDs across curated relationship types and return the nodes and edges reached. Use it to follow links from IDs you already have, such as a requirement to its scenarios and tests or a symbol to the requirements it implements; use kb_query to find entities by filter and kb_search to ask a question. Traversal stops at depth, maxNodes or maxEdges and then sets truncated. No mutation side effects.";
     readonly businessInputSchema: {
         readonly type: "object";
         readonly required: readonly ["seedIds"];
@@ -454,37 +467,44 @@ export declare const OPERATION_CATALOG: readonly [{
                 readonly items: {
                     readonly type: "string";
                 };
+                readonly description: "Entity IDs to start from, for example REQ-... or SCEN-.... Seeds are always returned as nodes.";
             };
             readonly relationships: {
                 readonly type: "array";
                 readonly items: {
                     readonly type: "string";
                 };
+                readonly description: "Relationship types to follow, for example specified_by, verified_by or implements. Omit to follow every relationship type.";
             };
             readonly direction: {
                 readonly type: "string";
                 readonly enum: readonly ["outgoing", "incoming", "both"];
                 readonly default: "outgoing";
+                readonly description: "outgoing follows links from each node, incoming follows links pointing at it, both does either.";
             };
             readonly depth: {
                 readonly type: "integer";
                 readonly default: 1;
                 readonly minimum: 1;
                 readonly maximum: 5;
+                readonly description: "Number of hops from the seeds.";
             };
             readonly entityTypes: {
                 readonly type: "array";
                 readonly items: {
                     readonly type: "string";
                 };
+                readonly description: "Keep only nodes of these types (req, scenario, test, adr, flag, event, symbol, fact) in the result, and the edges between them. Traversal still passes through other types.";
             };
             readonly maxNodes: {
                 readonly type: "integer";
                 readonly default: 200;
+                readonly description: "Stop and set truncated once this many nodes are reached.";
             };
             readonly maxEdges: {
                 readonly type: "integer";
                 readonly default: 500;
+                readonly description: "Stop and set truncated once this many edges are reached.";
             };
         };
     };
@@ -723,7 +743,7 @@ export declare const OPERATION_CATALOG: readonly [{
 }, {
     readonly name: "kb_model";
     readonly cliName: "model";
-    readonly description: "Turn requirement prose into checkable structure without writing the KB. mode:analyze returns the semantic advisor receipt: the clause ledger, what is grounded, what is ambiguous and suggested modeling (pass clauses for compound prose and optional typed kibi.logic.v1 interpretations). mode:requirement converts one claim (subjectKey, propertyKey, operator, value, or typed logic) into a strict-lane write set and applyPlan. mode:predicates ranks ontology predicate schemas and returns an applicable predicate-fact plan only for reviewed bindings, otherwise an ontology-gap observation. With requirementId, mode:predicates also returns a hash-bound plan (fact write plus requires_predicate link) for kb_apply_plan, whose contradictionAnalysis is the what-if over the current KB; other returned plans apply with kb_upsert, and kb_upsert dryRun with plannedFacts previews a requirement before its facts exist.";
+    readonly description: "Turn requirement prose into checkable structure without writing the KB. Use it for one requirement's prose; to plan a whole change request use kb_compile_intent. mode:analyze returns the semantic advisor receipt: the clause ledger, what is grounded, what is ambiguous and suggested modeling (pass clauses for compound prose and optional typed kibi.logic.v1 interpretations). mode:requirement converts one claim (subjectKey, propertyKey, operator, value, or typed logic) into a strict-lane write set and applyPlan. mode:predicates ranks ontology predicate schemas and returns an applicable predicate-fact plan only for reviewed bindings, otherwise an ontology-gap observation. With requirementId, mode:predicates also returns a hash-bound plan (fact write plus requires_predicate link) for kb_apply_plan, whose contradictionAnalysis is the what-if over the current KB; other returned plans apply with kb_upsert, and kb_upsert dryRun with plannedFacts previews a requirement before its facts exist.";
     readonly businessInputSchema: {
         readonly type: "object";
         readonly required: readonly ["mode", "text"];
@@ -741,7 +761,7 @@ export declare const OPERATION_CATALOG: readonly [{
 }, {
     readonly name: "kb_plan_bootstrap";
     readonly cliName: "plan-bootstrap";
-    readonly description: "Generate a deterministic, snapshot-bound kibi.bootstrap-plan.v1 for repository onboarding. Read-only analysis of the repository plus any declared knowledge sources and cited intent claims returns evidence, bounded context questions, exact dependency-ordered actions, a canonical plan hash, and no mutation side effects.";
+    readonly description: "Generate a deterministic, snapshot-bound kibi.bootstrap-plan.v1 for repository onboarding. Use it only to onboard a repository whose KB is empty or incomplete (the kibi-bootstrap skill drives it); for a change in an onboarded project use kb_compile_intent. Read-only analysis of the repository plus any declared knowledge sources and cited intent claims returns evidence, bounded context questions, exact dependency-ordered actions, a canonical plan hash, and no mutation side effects.";
     readonly businessInputSchema: {
         readonly type: "object";
         readonly properties: {
@@ -1839,7 +1859,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, 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 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, kb-consistency, kb-consistency-unresolved. 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";
@@ -1882,13 +1902,14 @@ export declare const OPERATION_CATALOG: readonly [{
 }, {
     readonly name: "kb_prepare_impact_review";
     readonly cliName: "prepare-impact-review";
-    readonly description: "Prepare complete content-bound impact-review authoring inputs from the current staged snapshot or explicitly selected immutable Git commits. Returns strict reviewer schemas and an unauthored template; it does not decide, approve, sign, stage, or prove the review.";
+    readonly description: "Prepare complete content-bound impact-review authoring inputs from the current staged snapshot or explicitly selected immutable Git commits. Use it when kb_check reports that changed files need an impact review; it does not plan KB changes. Returns strict reviewer schemas and an unauthored template; it does not decide, approve, sign, stage, or prove the review.";
     readonly businessInputSchema: {
         readonly type: "object";
         readonly additionalProperties: false;
         readonly required: readonly ["scope"];
         readonly properties: {
             readonly scope: {
+                readonly description: "What to review: {\"kind\":\"staged\"} for the staged snapshot, or {\"kind\":\"diff\",\"baseCommit\":\"<sha>\",\"headCommit\":\"<sha>\"} with full commit hashes.";
                 readonly oneOf: readonly [{
                     readonly type: "object";
                     readonly additionalProperties: false;
@@ -1951,7 +1972,7 @@ export declare const OPERATION_CATALOG: readonly [{
 }, {
     readonly name: "kb_compile_intent";
     readonly cliName: "compile-intent";
-    readonly description: "Compile complete change intent into a deterministic, snapshot-bound read-only plan. Reuses intent-aware discovery and semantic modeling, accounts for every proposition, reports contradiction witnesses, proposes traceability links, and emits dependency-ordered kb_upsert-style steps only for resolved typed claims. contradictionAnalysis.outcome is no_conflict only when the check could decide: an unmodeled proposition or a related current requirement without logic leaves it unresolved with reasons and reviewCandidates to compare and judge through conflictReviews. No mutation side effects.";
+    readonly description: "Compile complete change intent into a deterministic, snapshot-bound read-only plan. Use it before editing code for a change request that may touch several requirements; use kb_model for one requirement's prose and kb_plan_bootstrap for first-time onboarding. Reuses intent-aware discovery and semantic modeling, accounts for every proposition, reports contradiction witnesses, proposes traceability links, and emits dependency-ordered kb_upsert-style steps only for resolved typed claims. contradictionAnalysis.outcome is no_conflict only when the check could decide: an unmodeled proposition or a related current requirement without logic leaves it unresolved with reasons and reviewCandidates to compare and judge through conflictReviews. No mutation side effects.";
     readonly businessInputSchema: {
         readonly type: "object";
         readonly required: readonly ["intent", "mode"];

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

@@ -1 +1 @@
-{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../../src/public/operations/catalog.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../../src/public/operations/catalog.ts"],"names":[],"mappings":"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"}

package/dist/public/operations/contracts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../../src/public/operations/contracts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,0BAA0B,EAC1B,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB,oEAAoE;AACpE,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAsZpE;;uEAEuE;AACvE,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,mBAAmB,GAC1B,mBAAmB,CAMrB;AAqaD,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAC3C,MAAM,CAAC,aAAa,EAAE,mBAAmB,CAAC,CAa3C,CAAC;AAmDF,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,EAClD,YAAY,EAAE,MAAM,GACnB,IAAI,CAIN;AAED,wBAAgB,eAAe,CAC7B,SAAS,EAAE,aAAa,EACxB,OAAO,EAAE,SAAS,eAAe,EAAE,GAClC,SAAS,0BAA0B,EAAE,CAoBvC"}
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../../src/public/operations/contracts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,0BAA0B,EAC1B,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB,oEAAoE;AACpE,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAsZpE;;uEAEuE;AACvE,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,mBAAmB,GAC1B,mBAAmB,CAMrB;AAuaD,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAC3C,MAAM,CAAC,aAAa,EAAE,mBAAmB,CAAC,CAa3C,CAAC;AAmDF,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,EAClD,YAAY,EAAE,MAAM,GACnB,IAAI,CAIN;AAED,wBAAgB,eAAe,CAC7B,SAAS,EAAE,aAAa,EACxB,OAAO,EAAE,SAAS,eAAe,EAAE,GAClC,SAAS,0BAA0B,EAAE,CAoBvC"}

package/dist/public/operations/contracts.js

@@ -538,6 +538,7 @@ const BASE_DATA_SCHEMAS = {
         warnings: valueArray,
         semanticAdvisor: nullableJsonSchema(recordValue),
         normalizedPreview: nullableJsonSchema(recordValue),
+        errorCode: stringValue,
         stagedFacts: stringArray,
         whatIf: recordValue,
     }),
@@ -566,6 +567,7 @@ const BASE_DATA_SCHEMAS = {
                 warnings: valueArray,
                 semanticAdvisor: nullableJsonSchema(recordValue),
                 normalizedPreview: nullableJsonSchema(recordValue),
+                errorCode: stringValue,
                 stagedFacts: stringArray,
                 whatIf: recordValue,
                 dryRun: { const: true },

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

@@ -4,7 +4,7 @@ export { executePlanBootstrap } from "../../../operations/bootstrap/generate.js"
 export declare const planBootstrapSpec: {
     readonly name: "kb_plan_bootstrap";
     readonly cliName: "plan-bootstrap";
-    readonly description: "Generate a deterministic, snapshot-bound kibi.bootstrap-plan.v1 for repository onboarding. Read-only analysis of the repository plus any declared knowledge sources and cited intent claims returns evidence, bounded context questions, exact dependency-ordered actions, a canonical plan hash, and no mutation side effects.";
+    readonly description: "Generate a deterministic, snapshot-bound kibi.bootstrap-plan.v1 for repository onboarding. Use it only to onboard a repository whose KB is empty or incomplete (the kibi-bootstrap skill drives it); for a change in an onboarded project use kb_compile_intent. Read-only analysis of the repository plus any declared knowledge sources and cited intent claims returns evidence, bounded context questions, exact dependency-ordered actions, a canonical plan hash, and no mutation side effects.";
     readonly businessInputSchema: {
         readonly type: "object";
         readonly properties: {