kibi-cli 2.29.0 → 2.30.0

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: {

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

@@ -5,7 +5,7 @@ export { executePlanBootstrap } from "../../../operations/bootstrap/generate.js"
 export const planBootstrapSpec = {
     name: "kb_plan_bootstrap",
     cliName: "plan-bootstrap",
-    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.",
+    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.",
     businessInputSchema: {
         type: "object",
         properties: {

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

@@ -344,7 +344,7 @@ export declare const skillsSpec: {
 export declare const modelSpec: {
     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"];

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

@@ -152,7 +152,7 @@ export const skillsSpec = {
 export const modelSpec = {
     name: "kb_model",
     cliName: "model",
-    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.",
+    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.",
     businessInputSchema: {
         type: "object",
         required: ["mode", "text"],

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

@@ -233,7 +233,7 @@ export declare const searchSpec: {
 export declare const statusSpec: {
     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: {};

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

@@ -212,7 +212,7 @@ export const searchSpec = {
 export const statusSpec = {
     name: "kb_status",
     cliName: "status",
-    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.",
+    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.",
     businessInputSchema: { type: "object", properties: {} },
     // Status must remain available when the branch store cannot be attached.
     requiresProlog: false,

package/dist/public/operations/specs/impact-review-preparation.d.ts

@@ -2,13 +2,14 @@ import { executePrepareImpactReview } from "../impact-review-preparation.js";
 export declare const prepareImpactReviewSpec: {
     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;

package/dist/public/operations/specs/impact-review-preparation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"impact-review-preparation.d.ts","sourceRoot":"","sources":["../../../../src/public/operations/specs/impact-review-preparation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAG7E,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0CF,CAAC"}
+{"version":3,"file":"impact-review-preparation.d.ts","sourceRoot":"","sources":["../../../../src/public/operations/specs/impact-review-preparation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAG7E,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4CF,CAAC"}

package/dist/public/operations/specs/impact-review-preparation.js

@@ -2,13 +2,14 @@ import { executePrepareImpactReview } from "../impact-review-preparation.js";
 export const prepareImpactReviewSpec = {
     name: "kb_prepare_impact_review",
     cliName: "prepare-impact-review",
-    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.",
+    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.",
     businessInputSchema: {
         type: "object",
         additionalProperties: false,
         required: ["scope"],
         properties: {
             scope: {
+                description: 'What to review: {"kind":"staged"} for the staged snapshot, or {"kind":"diff","baseCommit":"<sha>","headCommit":"<sha>"} with full commit hashes.',
                 oneOf: [
                     {
                         type: "object",

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

@@ -8,7 +8,7 @@ export { executeCompileIntent } from "../../../operations/planning/compile-inten
 export declare const compileIntentSpec: {
     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/specs/planning.js

@@ -6,7 +6,7 @@ export { executeCompileIntent } from "../../../operations/planning/compile-inten
 export const compileIntentSpec = {
     name: "kb_compile_intent",
     cliName: "compile-intent",
-    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.",
+    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.",
     businessInputSchema: {
         type: "object",
         required: ["intent", "mode"],

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

@@ -69,42 +69,49 @@ export declare function executeFindGaps(input: FindGapsInput, context: Operation
 export declare const findGapsSpec: {
     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.";
             };
         };
     };
@@ -134,7 +141,7 @@ export declare function executeCoverage(input: CoverageInput, context: Operation
 export declare const coverageSpec: {
     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 proven 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: {
@@ -142,16 +149,19 @@ export declare const coverageSpec: {
                 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 proven or not applicable. By default only rows that still need repair are returned.";
             };
             readonly statuses: {
                 readonly type: "array";
@@ -164,14 +174,17 @@ export declare const coverageSpec: {
             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";
@@ -215,7 +228,7 @@ export declare function executeGraph(input: GraphInput, context: OperationContex
 export declare const graphSpec: {
     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"];
@@ -225,37 +238,44 @@ export declare const graphSpec: {
                 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.";
             };
         };
     };

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

@@ -1 +1 @@
-{"version":3,"file":"reporting.d.ts","sourceRoot":"","sources":["../../../../src/public/operations/specs/reporting.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,KAAK,aAAa,EAInB,MAAM,sBAAsB,CAAC;AAM9B,OAAO,EAAE,KAAK,UAAU,EAAmB,MAAM,mBAAmB,CAAC;AACrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAK5D,OAAO,KAAK,EAAE,eAAe,EAAiB,MAAM,aAAa,CAAC;AAelE,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,oBAAoB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClD,QAAQ,CAAC,oBAAoB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClD,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;IAC5D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxE,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACnD,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,EAAE,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACxC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAC3C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,uBAAuB,CAAC,EAAE,MAAM,CAAC;IAC1C,QAAQ,CAAC,0BAA0B,CAAC,EAAE,MAAM,CAAC;CAC9C,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,IAAI,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;IAC5D,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;IACnD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC9D,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACnD,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,SAAS,CAAC,EAAE,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;IACtD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;IAC7D,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;IAC7D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACnD,CAAC;AAiCF,wBAAsB,eAAe,CACnC,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,eAAe,CAAC,CAAC,CA+B3C;AAED,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuByC,CAAC;AAEnE;;;;;;;GAOG;AAEH,wBAAgB,uBAAuB,IAAI,cAAc,GAAG,iBAAiB,CAI5E;AAGD,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA0CxB;AAED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAGzC,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,WAAW,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,EAC/C,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,MAAM,EAClD,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,eAAe,CAAC,CAoB1B;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,eAAe,CAAC,CAAC,CA4H3C;AAED,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgEyC,CAAC;AAEnE,wBAAsB,YAAY,CAChC,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC,CA8BxC;AAED,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyBsC,CAAC"}
+{"version":3,"file":"reporting.d.ts","sourceRoot":"","sources":["../../../../src/public/operations/specs/reporting.ts"],"names":[],"mappings":"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"}

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

@@ -70,20 +70,44 @@ export async function executeFindGaps(input, context) {
 export const findGapsSpec = {
     name: "kb_find_gaps",
     cliName: "find-gaps",
-    description: "Run bulk missing/present relationship analysis over KB entities. Use for questions like which requirements lack scenarios or tests. No mutation side effects.",
+    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.",
     businessInputSchema: {
         type: "object",
         properties: {
             type: {
                 type: "string",
                 enum: ENTITY_TYPES,
+                description: "Only report entities of this type. Omit for all types.",
+            },
+            missingRelationships: {
+                type: "array",
+                items: { type: "string" },
+                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.",
+            },
+            presentRelationships: {
+                type: "array",
+                items: { type: "string" },
+                description: "Relationship types the entity must have at least one of each, in either direction.",
+            },
+            tags: {
+                type: "array",
+                items: { type: "string" },
+                description: "Keep entities carrying any of these metadata tags. Bootstrap provenance stubs appear in rows only when this names bootstrap:provenance-stub.",
+            },
+            sourceFile: {
+                type: "string",
+                description: "Keep entities whose source path contains this substring.",
+            },
+            limit: {
+                type: "integer",
+                default: 100,
+                description: "Maximum rows to return; count reports the full total.",
+            },
+            offset: {
+                type: "integer",
+                default: 0,
+                description: "Zero-based row offset for pagination.",
             },
-            missingRelationships: { type: "array", items: { type: "string" } },
-            presentRelationships: { type: "array", items: { type: "string" } },
-            tags: { type: "array", items: { type: "string" } },
-            sourceFile: { type: "string" },
-            limit: { type: "integer", default: 100 },
-            offset: { type: "integer", default: 0 },
         },
     },
     requiresProlog: true,
@@ -282,13 +306,26 @@ export async function executeCoverage(input, context) {
 export const coverageSpec = {
     name: "kb_coverage",
     cliName: "coverage",
-    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.",
+    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 proven 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.",
     businessInputSchema: {
         type: "object",
         properties: {
-            by: { type: "string", enum: ["req", "symbol", "type"], default: "req" },
-            tags: { type: "array", items: { type: "string" } },
-            includePassing: { type: "boolean", default: false },
+            by: {
+                type: "string",
+                enum: ["req", "symbol", "type"],
+                default: "req",
+                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.",
+            },
+            tags: {
+                type: "array",
+                items: { type: "string" },
+                description: "Keep rows for entities carrying any of these metadata tags.",
+            },
+            includePassing: {
+                type: "boolean",
+                default: false,
+                description: "Also return rows that are already proven or not applicable. By default only rows that still need repair are returned.",
+            },
             statuses: {
                 type: "array",
                 items: {
@@ -297,9 +334,21 @@ export const coverageSpec = {
                 },
                 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.",
             },
-            includeTransitive: { type: "boolean", default: true },
-            limit: { type: "integer", default: 100 },
-            offset: { type: "integer", default: 0 },
+            includeTransitive: {
+                type: "boolean",
+                default: true,
+                description: "Count symbol coverage reached transitively through linked entities, not only direct links.",
+            },
+            limit: {
+                type: "integer",
+                default: 100,
+                description: "Maximum rows to return. When the repair plan reports scope.complete false, rerun with offset 0 and a larger limit.",
+            },
+            offset: {
+                type: "integer",
+                default: 0,
+                description: "Zero-based row offset for pagination.",
+            },
             includeMigrationPreview: {
                 type: "boolean",
                 default: false,
@@ -367,22 +416,49 @@ export async function executeGraph(input, context) {
 export const graphSpec = {
     name: "kb_graph",
     cliName: "graph",
-    description: "Run bounded graph traversal from one or more seed IDs across curated relationship types. No mutation side effects.",
+    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.",
     businessInputSchema: {
         type: "object",
         required: ["seedIds"],
         properties: {
-            seedIds: { type: "array", items: { type: "string" } },
-            relationships: { type: "array", items: { type: "string" } },
+            seedIds: {
+                type: "array",
+                items: { type: "string" },
+                description: "Entity IDs to start from, for example REQ-... or SCEN-.... Seeds are always returned as nodes.",
+            },
+            relationships: {
+                type: "array",
+                items: { type: "string" },
+                description: "Relationship types to follow, for example specified_by, verified_by or implements. Omit to follow every relationship type.",
+            },
             direction: {
                 type: "string",
                 enum: ["outgoing", "incoming", "both"],
                 default: "outgoing",
+                description: "outgoing follows links from each node, incoming follows links pointing at it, both does either.",
+            },
+            depth: {
+                type: "integer",
+                default: 1,
+                minimum: 1,
+                maximum: 5,
+                description: "Number of hops from the seeds.",
+            },
+            entityTypes: {
+                type: "array",
+                items: { type: "string" },
+                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.",
+            },
+            maxNodes: {
+                type: "integer",
+                default: 200,
+                description: "Stop and set truncated once this many nodes are reached.",
+            },
+            maxEdges: {
+                type: "integer",
+                default: 500,
+                description: "Stop and set truncated once this many edges are reached.",
             },
-            depth: { type: "integer", default: 1, minimum: 1, maximum: 5 },
-            entityTypes: { type: "array", items: { type: "string" } },
-            maxNodes: { type: "integer", default: 200 },
-            maxEdges: { type: "integer", default: 500 },
         },
     },
     requiresProlog: true,

package/dist/public/skills/kibi-commit-review/SKILL.md

@@ -0,0 +1,125 @@
+---
+id: kibi-commit-review
+name: kibi-commit-review
+description: "Use when kibi check --staged or the Kibi pre-commit hook blocks a commit (kibi_impact_evidence_missing, symbols_manifest_stale, symbol_granularity_violation, symbol-coverage, kibi check-generated drift, Staged impact review failed), or when preparing a commit or pull-request impact review. Covers reading the per-file Detail lines, authoring .kb/symbols.yaml symbol entries through kb_upsert, kibi sync --refresh-symbol-coordinates, staging the tracked Kibi evidence with git add, kb_prepare_impact_review for a staged or diff scope, the kibi signoff requirements summary to show before a commit, and how merge commits and migration renames are judged."
+version: 1.2.0
+kibiCompatibility: ">=1.0.0"
+tags:
+  - kibi
+  - commit
+  - staged-check
+  - traceability
+  - agent-guidance
+resources:
+  - resources/staged-gate.md
+---
+## Goal
+
+Get a commit through Kibi's staged gate by fixing the cause: the commit
+carries the knowledge its behavior change needs, with current symbol
+coordinates, so the gate passes for the same reason a reviewer would accept it.
+
+## Interface Selection
+
+Use the visible approved MCP tools or the trusted project-local CLI as equal
+peer interfaces (CLI JSON: `printf '%s\n' '{}' | npx --no-install kibi status
+--input -`). The gate itself is CLI: `npx --no-install kibi check --staged`
+(add `--format json` for the full evidence). If neither surface is available,
+stop and name the missing capability. Never read or edit `.kb/` files directly.
+
+## When this applies
+
+- `kibi check --staged` fails, or the pre-commit hook (`kibi check-generated
+  --staged --changed-only`, then `kibi check --staged`) blocks a commit.
+- You are about to commit or open a pull request and want the impact review
+  ready first.
+
+Never read or open any file under `.kb`, not even read-only with a file tool to look at symbols or coordinates; doing so fails the session even when nothing is written. What you need is already shown elsewhere: the gate's `Detail:` lines, `kb_query` by `sourceFile` or `id`, and `kb_check` with `staged: true` show which symbols and coordinates are covered and which are missing. Before deciding what the change is, always run `kb_search` with `sourceLocations` for each named file and `kb_query` the requirement that governs it, even when the edit looks coordinate-only or seems to contradict a firm rule. When a write is authorized, keep the supplied target and its intended edges, query those targets first, validate the exact payload with `kb_upsert` and `dryRun: true`, then send that same payload with `kb_upsert` and exact-read the result back with `kb_query` before the final checks. Distinct authorized payloads may need several sequential writes, but never resend a write that is already committed, and let typed `nextActions` drive recovery. A passing dry run is validation only, not completion.
+
+## Steps
+
+1. **Read the whole failure.** Each finding names an id, the files, `Detail:`
+   lines and a `Suggestion:`. Detail lines are complete per file: how many
+   symbols extraction finds in the staged content, how many the staged
+   evidence covers, and every symbol missing from `.kb/symbols.yaml` with its
+   line. The common ids and their fixes are in `resources/staged-gate.md`.
+2. **Find the owning knowledge.** `kb_search` with `sourceLocations` for each
+   named file (or `kb_query({sourceFile})`), then `kb_query` the requirements,
+   scenarios and tests it returns. Run `kb_check` with `sourceFiles`,
+   `includeImpactDiagnostics: true` and `staged: true` to see the impact
+   findings, including `requirement_statement_unverified` quotes.
+3. **Decide what the change is.**
+   - Behavior changed: update or record the knowledge (a requirement with a
+     scenario, or a new clause) through `kb_upsert`. If the change contradicts
+     a recorded rule, stop and ask; load `kibi-decisions`.
+   - New or uncovered symbols: author a `symbol` entity per listed symbol
+     through `kb_upsert` (`title` = the member the extractor names,
+     `sourceFile`, `status: active`, `symbol_role: behavioral`, `implements`
+     to the requirement, `covered_by` to the test). Then run
+     `kibi sync --refresh-symbol-coordinates`.
+   - Only coordinates moved: `kibi sync --refresh-symbol-coordinates`.
+   - No behavior change (a genuine false positive): see the audited
+     no-impact note in `resources/staged-gate.md`; it never covers a real
+     behavior change.
+4. **Stage the evidence.** Kibi authors tracked files but never Git-stages or
+   commits them. `git status --short .kb` lists what it wrote; `git add` the
+   entity Markdown, `.kb/relationships/` shards, `.kb/symbols.yaml` and
+   `.kb/symbol-coordinates.yaml` that belong to this change (use `git add -p`
+   when the files hold unrelated edits).
+5. **Re-run** `kibi check --staged` (and `kibi check-generated --staged` when it
+   failed) until it passes. Never bypass the hook (`--no-verify`) unless the
+   person says so.
+
+## Requirements signoff
+
+Before you ask the person to approve a commit that adds, rewrites or retires
+requirements, or changes code that implements them, show them what they are
+signing off:
+
+```
+npx --no-install kibi signoff            # working tree; --staged for the index
+```
+
+It prints Markdown listing each new, changed, affected and retired
+requirement with its statement (before and after for a rewrite), firmness,
+origin, scenarios and proof state. Put it in your reply unchanged (in the
+messaging tool's message when replies go through one), then add one or two
+sentences on why the requirements changed. Offer the full page with
+`kibi signoff --format html --open`, or attach or publish
+`.kb/briefs/signoff/latest.html` when your host can carry a file or a page;
+past 15 requirements the Markdown stops and only the page lists them all.
+Host details: `kibi-decisions`, `resources/signoff-views.md`. `--no-proof` skips the proof lookup, which reads coverage and is slow
+on a large knowledge base. The summary is not an approval: never set
+`approved_by` or `origin.ref` from it.
+
+## Impact reviews
+
+When the repository's base commit carries `.kibi/impact-policy.json`, the gate
+also demands a content-bound review record at `.kibi/impact-review.json`
+(`Staged impact review failed: impact_review_invalid ...`). Prepare it with
+`kb_prepare_impact_review` (`scope: {"kind":"staged"}`, or `{"kind":"diff",
+"baseCommit":"<40-hex sha>","headCommit":"<40-hex sha>"}` for a pull
+request). It is read-only: it returns per-file evidence, requirement scopes,
+residual review obligations and an unauthored record template. Draft each
+file's `decision` from what you verified, leave `reviewer.id` for the person
+who reviews, and never present the record as their approval. Field details are
+in `resources/staged-gate.md`.
+
+## Merge commits and migrations
+
+During a merge (`MERGE_HEAD` exists), files staged unchanged from a merged
+parent are skipped (`Merge commit: N staged file(s) are taken unchanged ...`);
+only what the merge resolved or edited is judged. A commit that moves
+knowledge into `.kb/` after `kibi migrate` is compared with the old paths
+(`Baseline: HEAD with N staged knowledge rename(s) ...`), and symbol records
+changed only by the migration are not judged as changed. Debt reported there
+came from the branch or the old layout; the full `kibi check` still shows it.
+
+## Typed results and report
+
+Parse `kibiProtocol`, `status`, diagnostics and typed `nextActions` on every
+Kibi write. On `committed_with_repairs`, run the repair actions and never
+resend the original write. Report the findings you fixed (id, file, what
+changed), the knowledge you recorded or confirmed still current, the files
+you staged, the final `kibi check --staged` result, and anything left for the
+person (an open rule conflict, an unauthored review decision).