kibi-cli 0.19.0 → 1.0.1

package/src/public/skills/kibi-usage/resources/source-authoring.md

@@ -0,0 +1,31 @@
+# Source-first authoring
+
+Tracked Markdown, YAML, symbol manifests, and relationship shards are the
+authoritative project memory. Prolog/RDF state is a rebuildable compiled
+artifact. Kibi may transactionally write tracked files, but it never stages or
+commits them; ordinary Git workflows remain responsible for review and merge.
+
+`kb_upsert` accepts `document.path` and `document.body`. Existing entities use
+their authored source by default and preserve body bytes when `body` is omitted.
+New requirements use `semantic_text` as their body. If a new entity has zero or
+multiple configured writable targets, provide an explicit workspace-relative
+`document.path`; absolute, traversal, and symlink escapes are rejected.
+
+New files are compiled only while their exact bytes are covered by a pending-
+source receipt. Sync compiles Git-tracked files plus those hash-bound pending
+files; arbitrary untracked files are ignored. Stage the file in Git to absorb
+and remove its receipt. A changed or missing pending file is a blocking hash
+drift diagnostic. Unresolved Git index conflicts are likewise blocking; Kibi
+never chooses a merge winner.
+
+Relationship upserts and relationship deletes patch only the canonical shard,
+preserving unrelated records. Authored entity deletion returns a hash-bound
+plan; approve that plan through `kb_apply_plan`. Evolve requirements with a new
+requirement and `supersedes`, rather than deleting the old semantic claim.
+
+On `committed_with_repairs`, inspect `effects` and execute the typed required
+`nextActions`. Never retry the original mutation after its authoritative commit.
+Cancellation follows the same rule: wait for the terminal journal state. A
+pre-commit rollback is retryable, a committed source with a failed derivative
+is repairable, and an indeterminate outcome is non-retryable until its recovery
+action resolves the journal.

package/src/public/skills/kibi-usage/resources/workflows.md

@@ -1,5 +1,38 @@
 # Workflows
 
+## Closeout contract
+
+End every task with these five independent fields (not a single inferred
+success flag):
+
+```text
+taskOutcome: complete | interim | blocked
+kbState: clean_fresh | stale | dirty | legacy_compat | not_evaluated
+verificationState: fresh | dirty | unavailable | not_evaluated
+proofState: proven | mixed | unresolved | not_evaluated
+limitationDisposition: none | accepted | unaccepted | not_applicable
+```
+
+`taskOutcome` describes whether the requested objective was completed. The
+other fields describe observed system state. A clean check can coexist with a
+stale or dirty KB; unresolved proof can coexist with a complete maintenance
+task. An accepted limitation is an auditable operator decision, never logical
+grounding, receipt editing, or proof. For every quality diagnostic, record its
+ID, one of `fixed`, `accepted`, or `deferred`, and a rationale. Keep accepted
+ontology gaps and historical telemetry limitations explicit.
+
+Receipt reuse is safe only when the live verification snapshot, contract hash,
+freshness window, and every required case result still match. Otherwise rerun
+the contracted command. If the contract changed, retain every older receipt
+unchanged, append evidence for the current contract, and keep proof unresolved
+with `verification_contract_mismatch` until that current receipt exists.
+Obsolete symbols require current extraction or Git evidence before
+remap/deletion; transfer coverage only when existing test evidence supports it,
+then sync and read back status. Same-version packages with different export
+surfaces are a release defect: require a new package version and label any
+project override temporary. This skill never selects a package manager or
+edits dependency configuration.
+
 ## Discovery to Validation Sequence
 
 The canonical workflow for any KB operation follows this pattern:
@@ -13,7 +46,7 @@ The canonical workflow for any KB operation follows this pattern:
 7. **Create endpoints**: validated `kb_upsert` for new entities, sequentially
 8. **Link**: validated `kb_upsert` with `requires_rule`, `requires_predicate`, `constrains`, or `requires_property`, sequentially
 9. **Validate coverage and consistency**: targeted `rule-safety`, `rule-verifiability`, `semantic-completeness`, `logic-coverage`, `predicate-verifiability`, and `domain-contradictions`, then final full `kb_check`
-10. **Prove execution**: read `kb_status.verificationSnapshot`, run each scenario-backed E2E command, append its `kibi.verification-receipt.v1`, and re-run `kb_coverage`; never promote durable test status into fresh evidence
+10. **Prove execution**: read `kb_status.verificationSnapshot`, run each scenario-backed E2E command exactly as declared by its `verification_contract.v1` through `kibi verify`, append the derived `kibi.verification-receipt.v2`, and re-run `kb_coverage`; never promote durable test status into fresh evidence
 11. **Repair incrementally**: require `kb_coverage.repairPlan.scope.complete`, apply only one `ready` dependency batch per requirement, validate before every sequential write, and rerun coverage before selecting the next batch
 12. **Gate workflow evidence**: when `.kb/usage.log` exists, run `kibi usage-metrics --format json --require-acceptance`; repair ranked telemetry diagnostics and never treat stale or insufficient evidence as a pass
 
@@ -23,6 +56,26 @@ Every current requirement without `logic_claims` remains visible as non-blocking
 
 `kibi.telemetry-acceptance.v1` evaluates the latest 200 usage events and keeps process health separate from graph correctness. It requires at least 95% complete diagnostic telemetry and, when applicable, exact recent validation before every upsert and a same-requirement/current-hash advisor pass before requirement writes. It also evaluates source lookup misses, comparable complete-scope proof-gap recovery, receipt-specific coverage gaps, and mutation targets retried three or more times. Failed metrics become ranked `category: telemetry` quality diagnostics; missing current coverage fields or evidence older than seven days stays `insufficient_evidence`.
 
+## Agent-guided migration
+
+`kb_status`, unfiltered `kb_check`, and complete-scope `kb_coverage` may return
+the shared `kibi.migration-plan.v2`. Treat it as a typed action graph: inspect
+the canonical `planHash`, scope completeness, dependencies, safety class,
+preconditions, postconditions, and evidence. Apply only ready automatic actions
+with `autoApplicable: true` through an explicitly approved `kb_apply_plan` or
+`kibi migrate --apply-safe` request containing the exact hash and action IDs.
+Never infer an operation from a prose suggestion, and never apply a partial
+plan's destructive symbol or relationship action.
+
+The migration engine may normalize schema/config metadata, cut over validated
+legacy storage with backups, migrate the exact historical branch attachment,
+refresh coordinates, and perform provenance-proven stale cleanup. It does not
+choose package managers, ground semantic claims, resolve contradictions, rerun
+E2E tests, rewrite receipt history, remap authored symbols, or accept
+limitations. Those actions remain explicit review/operator/execution steps.
+
+For `e2e_receipt_freshness_low`, query each listed requirement/test gap and run its exact current contract through `kibi verify`; this appends v2 evidence and preserves older history. If `coverage_depth_review` conflicts with a coverage row whose `proofStages.passingE2e.status` is `passed`, report the diagnostic as a stale heuristic and keep any independent proof gaps unresolved.
+
 ## Creating a New Feature
 ```
 1. kb_search to discover existing requirements and related knowledge
@@ -50,10 +103,10 @@ Do not create a test-fact pair. Facts describe invariants; requirements or scena
 1. Confirm the exact `REQ -> SCEN -> TEST` path and require typed `verification_scope: end_to_end`; direct requirement-to-test links do not satisfy the conservative scenario stage.
 2. Read `kb_status` and retain its available `verificationSnapshot`. Stop if the runtime reports `unknown`; proof must fail closed when the code identity cannot be computed.
 3. Run the exact E2E command against that snapshot. Record runner, command, start/finish timestamps, outcome, an environment SHA-256, and an artifact/output SHA-256. Do not mint a passed receipt from an authored test status or from an unexecuted assertion.
-4. Preserve every existing receipt byte-for-byte and append a unique `kibi.verification-receipt.v1` object with strictly later `finished_at`. Mutation and incremental sync reject history removal, rewriting, and reordering.
+4. Preserve every existing receipt byte-for-byte and append the derived `kibi.verification-receipt.v2` object with strictly later `finished_at`. Earlier receipts may bind older contracts; they remain audit history but cannot prove the current contract. Mutation and incremental sync reject history removal, rewriting, and reordering.
 5. Re-read `kb_status`; if the snapshot changed during the run, discard the candidate as proof and rerun against the new snapshot. Then run `kb_coverage` and inspect `proofStages.passingE2e.receiptEvidence` plus gap codes.
 
-Only the newest receipt for the live snapshot qualifies, and it must be passed, no more than seven days old, and no more than five minutes in the future. Wrong-snapshot history is retained but stale for current proof. `missing_verification_receipt`, `stale_verification_receipt`, `failed_verification_receipt`, `invalid_verification_receipt`, and `verification_snapshot_unavailable` are repair states, not warnings to waive.
+Only the newest receipt matching both the live snapshot and current contract qualifies, and it must be passed, no more than seven days old, and no more than five minutes in the future. Wrong-snapshot and older-contract history is retained but cannot prove the current test. `missing_verification_receipt`, `stale_verification_receipt`, `failed_verification_receipt`, `invalid_verification_receipt`, `verification_contract_mismatch`, and `verification_snapshot_unavailable` are repair states, not warnings to waive.
 
 ## Predicate-First Requirement Modeling
 

package/src/public/symbol-granularity.ts

@@ -23,6 +23,7 @@ export const ALLOWED_GRANULARITY_REASONS = [
   "module-level-behavior",
   "extractor-miss",
   "legacy-link",
+  "test-suite",
 ] as const;
 
 export type GranularityReason = (typeof ALLOWED_GRANULARITY_REASONS)[number];

package/src/public/telemetry-acceptance.ts

@@ -43,6 +43,13 @@ export interface TelemetryUsageEvent {
   readonly coverage_scope_complete?: boolean;
   readonly coverage_proof_gap_count?: number;
   readonly coverage_receipt_gap_count?: number;
+  readonly coverage_receipt_gaps?: readonly Readonly<{
+    readonly requirementId: string;
+    readonly testIds: readonly string[];
+    readonly codes: readonly string[];
+  }>[];
+  readonly coverage_receipt_gap_total?: number;
+  readonly coverage_receipt_gaps_truncated?: boolean;
   readonly zero_results?: boolean;
   readonly result_count?: number;
   readonly error_category?: string;
@@ -570,6 +577,14 @@ function receiptFreshnessMetric(recent: readonly TimedEvent[]): MutableMetric {
       gapCount === 0
         ? "The latest complete requirement coverage event has no receipt-specific gaps."
         : `The latest complete requirement coverage event has ${gapCount} missing, stale, failed, invalid, or uncheckable receipt gaps.`,
+    evidence: {
+      receiptGaps: latest.coverage_receipt_gaps ?? [],
+      receiptGapTotal:
+        latest.coverage_receipt_gap_total ??
+        latest.coverage_receipt_gaps?.length ??
+        0,
+      receiptGapsTruncated: latest.coverage_receipt_gaps_truncated ?? false,
+    },
   };
 }
 
@@ -765,7 +780,7 @@ const METRIC_DIAGNOSTICS: Readonly<
     severity: "warning",
     rank: 40,
     suggestion:
-      "Run each scenario-backed E2E test against the live snapshot, append a passing kibi.verification-receipt.v1, sync, and rerun complete coverage.",
+      "Query the affected tests and run each exact current verification contract through kibi verify against the live snapshot; preserve history, append the generated kibi.verification-receipt.v2, and rerun complete coverage.",
   },
   repeated_mutation_failures: {
     id: "repeated_mutation_failures",

package/src/public/telemetry-remediation.ts

@@ -393,7 +393,7 @@ export function buildTelemetryRemediationReport(
             latestCoverage,
             "coverage:req",
             `The latest complete report has ${latestCoverage.event.coverage_receipt_gap_count} receipt gaps.`,
-            "Run the cited E2E tests, append fresh passing receipts, sync, and rerun coverage.",
+            "Query the cited tests and run each exact current verification contract through kibi verify; preserve receipt history, append the generated v2 receipts, sync, and rerun coverage.",
           )
         : reportItem(
             "e2e_receipt_freshness",

package/src/public/verification-receipt.ts

@@ -1,5 +1,13 @@
+import { createHash } from "node:crypto";
+
 export const VERIFICATION_RECEIPT_VERSION =
   "kibi.verification-receipt.v1" as const;
+// implements REQ-kibi-verification-evidence-contract
+export const VERIFICATION_RECEIPT_V2_VERSION =
+  "kibi.verification-receipt.v2" as const;
+// implements REQ-kibi-verification-evidence-contract
+export const VERIFICATION_CONTRACT_VERSION =
+  "kibi.verification-contract.v1" as const;
 
 export const VERIFICATION_RECEIPT_MAX_AGE_SECONDS = 7 * 24 * 60 * 60;
 
@@ -9,9 +17,11 @@ export const VERIFICATION_RECEIPT_OUTCOMES = [
   "errored",
   "cancelled",
   "skipped",
+  "timed_out",
+  "interrupted",
 ] as const;
 
-export const VERIFICATION_RECEIPT_SCHEMA = {
+const VERIFICATION_RECEIPT_V1_SCHEMA = {
   type: "object",
   required: [
     "version",
@@ -47,6 +57,87 @@ export const VERIFICATION_RECEIPT_SCHEMA = {
   additionalProperties: false,
 } as const;
 
+// implements REQ-kibi-verification-evidence-contract
+export const VERIFICATION_CONTRACT_SCHEMA = {
+  type: "object",
+  required: [
+    "version",
+    "runner",
+    "command_argv",
+    "required_case_symbols",
+    "required_projects",
+    "success_policy",
+  ],
+  properties: {
+    version: { type: "string", const: VERIFICATION_CONTRACT_VERSION },
+    runner: { type: "string", minLength: 1 },
+    command_argv: {
+      type: "array",
+      minItems: 1,
+      items: { type: "string", minLength: 1 },
+    },
+    required_case_symbols: {
+      type: "array",
+      items: { type: "string", minLength: 1 },
+      uniqueItems: true,
+    },
+    required_projects: {
+      type: "array",
+      items: { type: "string", minLength: 1 },
+      uniqueItems: true,
+    },
+    success_policy: {
+      type: "string",
+      const: "all_required_cases_first_attempt",
+    },
+  },
+  additionalProperties: false,
+} as const;
+
+const VERIFICATION_RECEIPT_V2_SCHEMA = {
+  ...VERIFICATION_RECEIPT_V1_SCHEMA,
+  required: [
+    ...VERIFICATION_RECEIPT_V1_SCHEMA.required,
+    "command_argv",
+    "contract_hash",
+    "case_results",
+  ],
+  properties: {
+    ...VERIFICATION_RECEIPT_V1_SCHEMA.properties,
+    version: { type: "string", const: VERIFICATION_RECEIPT_V2_VERSION },
+    command_argv: {
+      type: "array",
+      minItems: 1,
+      items: { type: "string", minLength: 1 },
+    },
+    contract_hash: { type: "string", pattern: "^[a-f0-9]{64}$" },
+    case_results: {
+      type: "array",
+      minItems: 1,
+      maxItems: 1000,
+      items: {
+        type: "object",
+        required: ["symbol_id", "project", "outcome", "retries", "duration_ms"],
+        properties: {
+          symbol_id: { type: "string", minLength: 1 },
+          project: { type: "string", minLength: 1 },
+          outcome: {
+            type: "string",
+            enum: ["passed", "failed", "timed_out", "skipped", "interrupted"],
+          },
+          retries: { type: "integer", minimum: 0 },
+          duration_ms: { type: "integer", minimum: 0 },
+        },
+        additionalProperties: false,
+      },
+    },
+  },
+} as const;
+
+export const VERIFICATION_RECEIPT_SCHEMA = {
+  oneOf: [VERIFICATION_RECEIPT_V1_SCHEMA, VERIFICATION_RECEIPT_V2_SCHEMA],
+} as const;
+
 export type VerificationReceipt = Readonly<{
   version: typeof VERIFICATION_RECEIPT_VERSION;
   receipt_id: string;
@@ -62,6 +153,31 @@ export type VerificationReceipt = Readonly<{
   artifact_digest: string;
 }>;
 
+// implements REQ-kibi-verification-evidence-contract
+export type VerificationReceiptV2 = VerificationReceipt &
+  Readonly<{
+    version: typeof VERIFICATION_RECEIPT_V2_VERSION;
+    command_argv: readonly string[];
+    contract_hash: string;
+    case_results: readonly {
+      symbol_id: string;
+      project: string;
+      outcome: "passed" | "failed" | "timed_out" | "skipped" | "interrupted";
+      retries: number;
+      duration_ms: number;
+    }[];
+  }>;
+
+// implements REQ-kibi-verification-evidence-contract
+export type VerificationContract = Readonly<{
+  version: typeof VERIFICATION_CONTRACT_VERSION;
+  runner: string;
+  command_argv: readonly string[];
+  required_case_symbols: readonly string[];
+  required_projects: readonly string[];
+  success_policy: "all_required_cases_first_attempt";
+}>;
+
 function timestamp(value: unknown): number | null {
   if (typeof value !== "string") return null;
   if (
@@ -101,12 +217,11 @@ export function verificationReceiptHistoryErrors(
       errors.push(`${prefix}.test_id must equal '${testId}'`);
     }
     if (
-      typeof verificationScope === "string" &&
-      receipt.scope !== verificationScope
+      !(["unit", "integration", "end_to_end"] as const).includes(
+        receipt.scope as "unit" | "integration" | "end_to_end",
+      )
     ) {
-      errors.push(
-        `${prefix}.scope must equal the test verification_scope '${verificationScope}'`,
-      );
+      errors.push(`${prefix}.scope must be a supported verification scope`);
     }
     const startedAt = timestamp(receipt.started_at);
     const finishedAt = timestamp(receipt.finished_at);
@@ -127,6 +242,126 @@ export function verificationReceiptHistoryErrors(
       );
     }
     if (finishedAt !== null) previousFinishedAt = finishedAt;
+    if (receipt.version === VERIFICATION_RECEIPT_V2_VERSION) {
+      if (
+        !Array.isArray(receipt.command_argv) ||
+        receipt.command_argv.length === 0 ||
+        receipt.command_argv.some(
+          (argument) => typeof argument !== "string" || argument.trim() === "",
+        )
+      ) {
+        errors.push(
+          `${prefix}.command_argv must be a non-empty argv of strings`,
+        );
+      }
+      if (
+        typeof receipt.contract_hash !== "string" ||
+        !/^[a-f0-9]{64}$/.test(receipt.contract_hash)
+      ) {
+        errors.push(`${prefix}.contract_hash must be a SHA-256 hex digest`);
+      }
+      const caseResults = receipt.case_results;
+      if (!Array.isArray(caseResults) || caseResults.length === 0) {
+        errors.push(
+          `${prefix}.case_results must contain at least one contracted case`,
+        );
+      } else {
+        const seenCases = new Set<string>();
+        for (const [caseIndex, caseResult] of caseResults.entries()) {
+          if (
+            !caseResult ||
+            typeof caseResult !== "object" ||
+            Array.isArray(caseResult)
+          ) {
+            errors.push(
+              `${prefix}.case_results[${caseIndex}] must be an object`,
+            );
+            continue;
+          }
+          const row = caseResult as Record<string, unknown>;
+          if (
+            typeof row.symbol_id !== "string" ||
+            row.symbol_id.trim() === "" ||
+            typeof row.project !== "string" ||
+            row.project.trim() === ""
+          ) {
+            errors.push(
+              `${prefix}.case_results[${caseIndex}] requires non-empty symbol_id and project`,
+            );
+          }
+          if (
+            ![
+              "passed",
+              "failed",
+              "timed_out",
+              "skipped",
+              "interrupted",
+            ].includes(String(row.outcome))
+          ) {
+            errors.push(
+              `${prefix}.case_results[${caseIndex}].outcome is not a supported result`,
+            );
+          }
+          const key = `${String(row.project ?? "")}\0${String(row.symbol_id ?? "")}`;
+          if (seenCases.has(key))
+            errors.push(
+              `${prefix}.case_results duplicates '${key.replace("\0", "/")}'`,
+            );
+          seenCases.add(key);
+          if (
+            typeof row.retries !== "number" ||
+            !Number.isInteger(row.retries) ||
+            row.retries < 0
+          )
+            errors.push(
+              `${prefix}.case_results[${caseIndex}].retries must be a non-negative integer`,
+            );
+          if (
+            typeof row.duration_ms !== "number" ||
+            !Number.isInteger(row.duration_ms) ||
+            row.duration_ms < 0
+          )
+            errors.push(
+              `${prefix}.case_results[${caseIndex}].duration_ms must be a non-negative integer`,
+            );
+        }
+      }
+    }
+  }
+  return errors;
+}
+
+// implements REQ-kibi-verification-evidence-contract
+export function verificationReceiptCurrentBindingErrors(
+  testId: string,
+  verificationScope: unknown,
+  receipt: Readonly<Record<string, unknown>>,
+  contract?: Readonly<Record<string, unknown>>,
+): readonly string[] {
+  const errors: string[] = [];
+  if (receipt.test_id !== testId) {
+    errors.push(`verification receipt test_id must equal '${testId}'`);
+  }
+  if (typeof verificationScope !== "string") {
+    errors.push("verification_scope is required for current receipt evidence");
+  } else if (receipt.scope !== verificationScope) {
+    errors.push(
+      `verification receipt scope must equal the current verification_scope '${verificationScope}'`,
+    );
+  }
+  if (contract !== undefined) {
+    if (receipt.version !== VERIFICATION_RECEIPT_V2_VERSION) {
+      errors.push(
+        "the current verification_contract requires a kibi.verification-receipt.v2",
+      );
+    } else if (typeof receipt.contract_hash === "string") {
+      const expectedHash = verificationContractHash(contract);
+      if (receipt.contract_hash !== expectedHash) {
+        errors.push(
+          "verification receipt contract_hash does not match the current verification_contract",
+        );
+      }
+    }
   }
   return errors;
 }
@@ -144,6 +379,13 @@ function canonicalJson(value: unknown): string {
   return JSON.stringify(value);
 }
 
+// implements REQ-kibi-verification-evidence-contract
+export function verificationContractHash(
+  contract: Readonly<Record<string, unknown>>,
+): string {
+  return createHash("sha256").update(canonicalJson(contract)).digest("hex");
+}
+
 export function appendOnlyVerificationReceiptHistoryErrors(
   previous: readonly Readonly<Record<string, unknown>>[],
   next: readonly Readonly<Record<string, unknown>>[] | undefined,