kibi-cli 2.16.0 → 2.18.0

package/src/public/operations/discovery-executors.ts

@@ -21,8 +21,10 @@ import {
   branchStoreReason,
   inspectBranchStore,
   storeLockJournalReason,
+  storeLockTakeoverReason,
   uncompiledBranchStoreReason,
 } from "../../utils/branch-store.js";
+import { confirmSourceNewerReasons } from "../../utils/content-freshness.js";
 import {
   loadEntities,
   loadSearchCandidates,
@@ -78,8 +80,47 @@ export type SearchPayload = {
   readonly truncated?: boolean;
   readonly queryAnalysis?: IntentSearchAnalysis;
   readonly answer?: SearchAnswer;
+  /** The Kibi branch whose store was searched, when the runtime attached one. */
+  readonly branch?: string | null;
+  /** Present when the searched store was never compiled for this branch. */
+  readonly branchStore?: SearchBranchStoreNotice;
 };
 
+export type SearchBranchStoreNotice = {
+  readonly state: "not_compiled";
+  readonly code: typeof BRANCH_STORE_NOT_COMPILED;
+  readonly path: string;
+  readonly detail: string;
+  readonly remediation: Readonly<Record<string, unknown>>;
+};
+
+/**
+ * An empty result from a store that was never compiled says nothing about
+ * the authored requirements, so search reports the store state itself (the
+ * same reason kb_status and kb_check use) instead of a bare "no results".
+ */
+// implements REQ-cli-status-pre-first-sync, REQ-mcp-search-discovery
+function uncompiledSearchNotice(
+  context: OperationContext,
+): SearchBranchStoreNotice | null {
+  const attachment = context.branchAttachment;
+  if (attachment === undefined) return null;
+  const store = inspectBranchStore(context.workspaceRoot, attachment.kbBranch);
+  const reason = uncompiledBranchStoreReason(
+    context.workspaceRoot,
+    store,
+    attachment.kbBranch,
+  );
+  if (reason === null) return null;
+  return {
+    state: "not_compiled",
+    code: BRANCH_STORE_NOT_COMPILED,
+    path: store.path,
+    detail: String(reason.detail),
+    remediation: reason.remediation as Readonly<Record<string, unknown>>,
+  };
+}
+
 export type StatusInput = Readonly<Record<string, never>>;
 
 export type StatusPayload = {
@@ -99,6 +140,8 @@ export type StatusPayload = {
   readonly staleReasons?: readonly Record<string, unknown>[];
   readonly staleReasonCount?: number;
   readonly staleReasonsTruncated?: boolean;
+  /** Informational, non-blocking observations (never make the KB stale). */
+  readonly notices?: readonly Record<string, unknown>[];
   readonly branchAttachment?: {
     readonly gitBranch: string;
     readonly kbBranch: string;
@@ -275,6 +318,15 @@ export async function executeSearch(
   validateEntityType(type);
   try {
     const prolog = requireProlog(context);
+    const branch = context.branchAttachment?.kbBranch ?? null;
+    const storeNotice = uncompiledSearchNotice(context);
+    const branchFields = {
+      branch,
+      ...(storeNotice ? { branchStore: storeNotice } : {}),
+    };
+    const storeNote = storeNotice
+      ? ` Note: ${storeNotice.detail} Run kibi sync before relying on search results.`
+      : "";
     const intentMode =
       rankingMode === "intent-v1" ||
       semanticFacets !== undefined ||
@@ -305,7 +357,7 @@ export async function executeSearch(
           : undefined;
       // The structured payload carries every row; the text is a short
       // human-readable digest instead of a second copy of the results.
-      const text =
+      const text = `${
         intentResult.matches.length === 0
           ? `No intent search results for '${trimmedQuery}' (abstained).`
           : `Found ${intentResult.matches.length} intent search results for '${trimmedQuery}'${intentResult.analysis.ambiguous ? " (top matches are close; confirm before relying on one)" : ""}. Top: ${paginated
@@ -313,7 +365,8 @@ export async function executeSearch(
               .map((match) => String(match.entity.id ?? ""))
               .join(
                 ", ",
-              )}${answerLayer ? `. Governing: ${answerLayer.governing.map((req) => req.id).join(", ") || "none found"}` : ""}.`;
+              )}${answerLayer ? `. Governing: ${answerLayer.governing.map((req) => req.id).join(", ") || "none found"}` : ""}.`
+      }${storeNote}`;
       return {
         content: [{ type: "text", text }],
         structuredContent: {
@@ -322,6 +375,7 @@ export async function executeSearch(
           truncated: offset + paginated.length < intentResult.matches.length,
           queryAnalysis: intentResult.analysis,
           ...(answerLayer ? { answer: answerLayer } : {}),
+          ...branchFields,
         },
       };
     }
@@ -342,7 +396,7 @@ export async function executeSearch(
       context.workspaceRoot,
     );
     const paginated = paginateResults(matches, limit, offset);
-    const text =
+    const text = `${
       matches.length === 0
         ? `No search results for '${trimmedQuery}'.`
         : `Found ${matches.length} search results for '${trimmedQuery}'. Showing ${paginated.length} (offset ${offset}, limit ${limit}): ${paginated
@@ -350,13 +404,15 @@ export async function executeSearch(
               (match) =>
                 `${String(match.entity.id ?? "")} [${match.reasons.join(", ")}]`,
             )
-            .join(", ")}`;
+            .join(", ")}`
+    }${storeNote}`;
     return {
       content: [{ type: "text", text }],
       structuredContent: {
         results: await projectMatches(prolog, paginated, fields),
         count: matches.length,
         truncated: offset + paginated.length < matches.length,
+        ...branchFields,
       },
     };
   } catch (error) {
@@ -460,7 +516,25 @@ export async function executeStatus(
         await ownedEngine?.terminate();
       }
     const snapshotEvidence = await readWorkspaceSnapshot(context);
-    const existingReasons = payload.staleReasons ?? [];
+    // implements REQ-cli-status-pre-first-sync
+    // Prolog compares file times only. A fresh clone or a checkout rewrites
+    // every mtime without changing a byte, so confirm each "newer" source
+    // against the content hashes the last compilation recorded.
+    const prologReasons = payload.staleReasons ?? [];
+    const confirmed = confirmSourceNewerReasons(
+      context.workspaceRoot,
+      store.path,
+      prologReasons,
+    );
+    const existingReasons = confirmed.kept;
+    if (
+      confirmed.dropped.length > 0 &&
+      confirmed.kept.length === 0 &&
+      payload.staleReasonsTruncated !== true &&
+      payload.syncState === "stale"
+    ) {
+      payload = { ...payload, syncState: "fresh", dirty: false };
+    }
     // implements REQ-cli-status-pre-first-sync
     // A missing or empty store beside authored sources gets the one reason
     // whose remediation works (kibi sync); `kibi branch ensure` alone would
@@ -473,6 +547,9 @@ export async function executeStatus(
       ) ?? branchStoreReason(store);
     const storeUncompiled = storeReason?.code === BRANCH_STORE_NOT_COMPILED;
     const lockReason = storeLockJournalReason(store.path);
+    // implements REQ-core-journaled-engine-persistence
+    // A stale-lock takeover heals itself; report it without making the KB stale.
+    const takeoverNotice = storeLockTakeoverReason(store.path);
     const compilerReason = compilerFingerprintReason(store.path);
     const engineReason = engineStatus
       ? {
@@ -507,13 +584,14 @@ export async function executeStatus(
       // Source hashes can all match while the compilation itself is lossy, so
       // a compiler contract change alone makes the store stale.
       ...(compilerReason ? { syncState: "stale", dirty: true } : {}),
-      // An empty store has no stale file to report, yet nothing in it is
-      // current: the authored sources were never compiled.
-      ...(storeUncompiled && store.state === "healthy"
-        ? { syncState: "stale", dirty: true }
-        : {}),
+      // A missing or empty store has no stale file to report, yet nothing in
+      // it is current: the authored sources were never compiled. (A missing
+      // store without authored sources, and an unreadable or incomplete one,
+      // stay "unknown".)
+      ...(storeUncompiled ? { syncState: "stale", dirty: true } : {}),
       branchAttachment: attachment,
       branchStore: store,
+      ...(takeoverNotice ? { notices: [takeoverNotice] } : {}),
       ...(engineStatus ? { engineStatus } : {}),
       staleReasons,
       staleReasonCount: staleReasons.length,
@@ -661,7 +739,7 @@ export async function executeStatus(
       content: [
         {
           type: "text",
-          text: `Branch ${payload.branch} is ${enrichedPayload.syncState} (snapshot ${payload.snapshotId}, dirty=${enrichedPayload.dirty}, proofSnapshot=${enrichedPayload.proofSnapshot})${storeUncompiled ? `. Blocking: ${String(storeReason?.detail)} Run kibi sync.` : ""}`,
+          text: `Branch ${payload.branch} is ${enrichedPayload.syncState} (snapshot ${payload.snapshotId}, dirty=${enrichedPayload.dirty}, proofSnapshot=${enrichedPayload.proofSnapshot})${storeUncompiled ? `. Blocking: ${String(storeReason?.detail)} Run kibi sync.` : ""}${takeoverNotice ? `. Note: ${String(takeoverNotice.detail)}` : ""}`,
         },
       ],
       structuredContent: statusWithPlan,

package/src/public/operations/migration-plan.ts

@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from "node:fs";
 import * as path from "node:path";
 import { BRANCH_STORE_NOT_COMPILED } from "../../utils/branch-store.js";
 import { legacyConfigExists } from "../../utils/config.js";
+import { MTIME_SOURCE_REASON_CODES } from "../../utils/content-freshness.js";
 import { readKbManifestStatus } from "../../utils/kb-manifest.js";
 import {
   getSchemaVersionStatus,
@@ -616,6 +617,9 @@ function readLegacySchemaVersion(
 }
 
 // implements REQ-agent-guided-migration-orchestration
+/** Migration action code of the automatic recompile of changed sources. */
+export const FRESHNESS_RESYNC = "freshness_resync";
+
 export function buildActionsFromStatus(input: {
   workspaceRoot: string;
   branchAttachment?: Readonly<Record<string, unknown>>;
@@ -777,10 +781,50 @@ export function buildActionsFromStatus(input: {
     );
   }
 
+  // implements REQ-cli-status-pre-first-sync
+  // Sources whose content changed since the last compilation (kb_status has
+  // already dropped mtime-only reasons) are fixed by recompiling them: one
+  // automatic `kibi sync`, not a review per file. An uncompiled store is
+  // compiled by the step above, which also covers these files.
+  const resyncReasons = (input.staleReasons ?? []).filter(
+    (reason) =>
+      typeof reason.code === "string" &&
+      MTIME_SOURCE_REASON_CODES.has(reason.code),
+  );
+  if (resyncReasons.length > 0 && uncompiled === undefined) {
+    actions.push(
+      migrationAction({
+        id: "freshness-resync",
+        code: FRESHNESS_RESYNC,
+        category: "freshness",
+        safety: "automatic",
+        invocation: { kind: "cli", command_argv: ["kibi", "sync"] },
+        affectedFiles: [
+          ...new Set(
+            resyncReasons.flatMap((reason) =>
+              typeof reason.path === "string" ? [reason.path] : [],
+            ),
+          ),
+        ].sort(),
+        evidence: { reasons: resyncReasons },
+        dependsOn: actions
+          .map((action) => action.id)
+          .filter(
+            (id) =>
+              id === "branch-store-ensure" || id === "schema-config-upgrade",
+          ),
+        postconditions: [{ syncState: "fresh" }],
+        autoApplicable: true,
+      }),
+    );
+  }
+
   for (const reason of input.staleReasons ?? []) {
     const code = typeof reason.code === "string" ? reason.code : "stale_source";
     // Planned above as an automatic compile step, not a review.
     if (code === BRANCH_STORE_NOT_COMPILED) continue;
+    // Planned above as one automatic resync (or covered by the compile).
+    if (MTIME_SOURCE_REASON_CODES.has(code)) continue;
     const file = typeof reason.path === "string" ? reason.path : "";
     actions.push(
       migrationAction({

package/src/public/operations/result-envelope.ts

@@ -1,3 +1,4 @@
+import { MIGRATION_PLAN_REFUSED } from "../../operations/planning/migration-refusal.js";
 import type { KibiResult, OperationEffect, OperationName } from "./types.js";
 
 export const KIBI_PROTOCOL_VERSION = 1 as const;
@@ -139,6 +140,16 @@ export function resultVersion(spec: {
   return spec.resultVersion ?? `kibi.${spec.name}.v1`;
 }
 
+function refusalDetail(row: Record<string, unknown>): string {
+  const results = Array.isArray(row.actionResults) ? row.actionResults : [];
+  const failure = results.find(
+    (entry) => record(entry) && entry.outcome === "failed",
+  );
+  return record(failure) && typeof failure.detail === "string"
+    ? failure.detail
+    : "";
+}
+
 export function toKibiResult<T>(
   spec: {
     readonly name: OperationName | string;
@@ -158,12 +169,17 @@ export function toKibiResult<T>(
   } = {},
 ): KibiResult<T> {
   const row = record(data) ? data : undefined;
+  // A migration plan whose actions were all refused changed nothing: it is
+  // an error, not a success that needs reconciliation.
+  const migrationRefused =
+    row?.version === "kibi.migration-apply-result.v1" &&
+    row.outcome === "refused";
   let status = options.status;
   if (!status) {
     status = "success";
     if (row?.status === "committed_with_repairs")
       status = "committed_with_repairs";
-    if (row?.status === "rejected") status = "error";
+    if (row?.status === "rejected" || migrationRefused) status = "error";
   }
   const terminalError =
     row?.status === "rejected"
@@ -173,9 +189,21 @@ export function toKibiResult<T>(
             "Bootstrap stopped at a deterministic failure. Inspect actionResults for committed actions and re-plan from the current state.",
           retryable: false,
         }
-      : undefined;
+      : migrationRefused
+        ? {
+            code: MIGRATION_PLAN_REFUSED,
+            message:
+              `Migration plan refused; nothing was changed. ${refusalDetail(row)}`.trim(),
+            retryable: false,
+          }
+        : undefined;
   const resultError = options.error ?? terminalError;
-  const outcome = effectOutcome(status, options);
+  const outcome = effectOutcome(
+    status,
+    migrationRefused && options.attempted === undefined
+      ? { ...options, attempted: false }
+      : options,
+  );
   return {
     kibiProtocol: KIBI_PROTOCOL_VERSION,
     operation: spec.name as OperationName,

package/src/public/operations/source-relationship-parity.ts

@@ -2,6 +2,7 @@ import { execFileSync } from "node:child_process";
 import path from "node:path";
 import { discoverSourceFiles } from "../../commands/sync/discovery.js";
 import { processExtractions } from "../../commands/sync/extraction.js";
+import { findUntrackedDocumentMatches } from "../../commands/sync/untracked-targets.js";
 import type { ExtractedRelationship } from "../../extractors/markdown.js";
 import { RELATIONSHIP_TYPES } from "../../operations/mutation/relationships.js";
 import { parseListOfLists, parsePrologValue } from "../../prolog/codec.js";
@@ -234,8 +235,64 @@ export async function collectSourceRelationshipParityViolations(
     });
   }
 
-  return compareRelationshipParity(
-    authored,
-    await compiledRelationships(prolog),
+  return explainUntrackedEndpoints(
+    workspaceRoot,
+    compareRelationshipParity(authored, await compiledRelationships(prolog)),
   );
 }
+
+/**
+ * An authored relationship is missing from the compiled KB most often
+ * because an endpoint is declared in a file sync cannot see: one Git does not
+ * track and no pending-source receipt covers (for example a `.kb/symbols.yaml`
+ * that `kibi init` created and kb_upsert appended to before receipts covered
+ * existing untracked files). Name that file and the fix.
+ */
+// implements REQ-kibi-source-relationship-parity
+function explainUntrackedEndpoints(
+  workspaceRoot: string,
+  violations: Violation[],
+): Violation[] {
+  const endpoints = new Set<string>();
+  for (const violation of violations) {
+    const relationship = authoredToCompiledRelationship(violation);
+    if (relationship === null) continue;
+    endpoints.add(relationship.from);
+    endpoints.add(relationship.to);
+  }
+  if (endpoints.size === 0) return violations;
+  const untracked = findUntrackedDocumentMatches(workspaceRoot, [...endpoints]);
+  if (untracked.size === 0) return violations;
+  return violations.map((violation) => {
+    const relationship = authoredToCompiledRelationship(violation);
+    if (relationship === null) return violation;
+    const sources = [relationship.from, relationship.to].flatMap((id) => {
+      const file = untracked.get(id);
+      return file === undefined ? [] : [{ entityId: id, file }];
+    });
+    if (sources.length === 0) return violation;
+    const files = [...new Set(sources.map((source) => source.file))];
+    return {
+      ...violation,
+      suggestion: `${sources.map((source) => source.entityId).join(" and ")} ${sources.length === 1 ? "is" : "are"} declared in ${files.join(", ")}, which Git does not track and no pending-source receipt covers, so sync never compiles it. Run 'git add ${files.join(" ")}' (staging is enough) or rewrite the entity with kb_upsert, then run kibi sync and rerun kb_check.`,
+      evidence: {
+        ...(violation.evidence ?? {}),
+        untrackedSources: sources,
+      },
+    };
+  });
+}
+
+function authoredToCompiledRelationship(
+  violation: Violation,
+): { from: string; to: string } | null {
+  const evidence = violation.evidence as
+    | { direction?: unknown; relationship?: { from?: unknown; to?: unknown } }
+    | undefined;
+  if (evidence?.direction !== "authored_to_compiled") return null;
+  const from = evidence.relationship?.from;
+  const to = evidence.relationship?.to;
+  return typeof from === "string" && typeof to === "string"
+    ? { from, to }
+    : null;
+}

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

@@ -2,7 +2,7 @@
 id: kibi-usage
 name: Kibi Usage
 description: Use Kibi's source-first, exact-Git, migration-aware, proof-aware operations safely across MCP or the trusted local CLI, including partial completion repair.
-version: 2.12.0
+version: 2.14.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -148,7 +148,13 @@ error `BOOTSTRAP_PLAN_REJECTED` can follow earlier committed actions: inspect
 `data.actionResults` and `data.applied`, then re-plan from the current state.
 Its journal is terminal; never recover or replay it. `BOOTSTRAP_PLAN_INVALID`
 fails preflight before bootstrap writes or a new journal; obtain a corrected
-plan. If the status is
+plan. A migration plan whose actions were refused before changing anything
+returns `status: error`, `MIGRATION_PLAN_REFUSED` and `data.outcome:
+refused`: nothing changed, so read the action `detail` and get a new plan.
+`data.outcome: reconciliation_required` (status success) means an action
+failed mid-way: inspect its effect before retrying. `kb_delete` of an
+authored entity returns status success with `deleted: 0`; its `errors` say
+why nothing was deleted. If the status is
 `committed_with_repairs`, the mutation already committed: inspect failed effects,
 execute each required repair action in order, and never retry the original
 operation. Record effect failures, followed actions, and unsafe retries in
@@ -231,7 +237,11 @@ authored. Each one is the order the write path accepts.
    fact, `requires_predicate` to `relationshipTarget` and `specified_by` to
    its scenario: `specified_by` (req → scenario) is sent in the
    requirement's write, never in the scenario's, so create the scenario
-   first. A
+   first, with `assumes` links (scenario → `property_value` fact, sent in
+   the scenario's own write) to the values its outcome relies on. Set
+   `expects` only on a scenario that has `assumes` links; `expects: success`
+   without them only yields `scenario-feasibility-unknown` ("assumes
+   nothing"). A
    `modeled` entry and its grounding link must arrive in the same write
    (`modeled semantic_inventory entries (n) must equal logical grounding
    relationships (m)`); a clause not grounded yet stays `status: missing`
@@ -243,7 +253,12 @@ authored. Each one is the order the write path accepts.
    claim_keys must match logical grounding target claim_keys exactly`.
    Prefer supersession for a change of meaning: analyze the new prose,
    write its facts, write the new requirement (`-v2`) with `supersedes` to
-   the old one, then set the old one to `status: closed`. For a wording fix
+   the old one, then set the old one to `status: closed`. Its scenario
+   follows the same rule as in recipe 1: create the new scenario (with
+   `assumes` to the `property_value` facts it relies on, and `expects` only
+   when it has them) before the `-v2` write that sends `specified_by`, then
+   re-point the old scenario (its `assumes` go in its own write) or close
+   it. For a wording fix
    that keeps the meaning, re-ground in place: analyze the new prose,
    `kb_upsert` each grounding fact with the new `claim_key`/`claim_text`
    (same fact id), then `kb_upsert` the requirement with the new ledger,

package/src/public/skills/kibi-usage/resources/fact-lanes.md

@@ -61,16 +61,16 @@ A schema can close an argument with `argument_constants` (allowed values keyed b
 
 ### Deny predicate
 
-Claim: “Suspended users must not publish articles.” When `permission_rule` fits, preserve its positive schema name and encode prohibition as polarity:
+Claim: “Suspended users must not publish articles.” When `permission_rule` fits, preserve its positive schema name and encode prohibition as polarity. `kb_model` (`mode: "predicates"`) plans this fact for the claim; the built-in schema's fourth argument, `decision`, repeats the polarity:
 
 ```yaml
 id: FACT-SUSPENDED-PUBLISH-DENIED
 status: active
 fact_kind: predicate
 predicate_name: permission_rule
-predicate_args: [suspended_user, publish, article]
+predicate_args: [suspended_user, publish, articles, deny]
 polarity: deny
-canonical_key: permission_rule(suspended_user,publish,article)
+canonical_key: permission_rule(suspended_user,publish,articles,deny)
 claim_key: <advisor-issued key for this exact clause>
 claim_text: Suspended users must not publish articles.
 relationship: { type: requires_predicate, from: REQ-SUSPENDED-PUBLISH-DENIED, to: FACT-SUSPENDED-PUBLISH-DENIED }

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

@@ -51,6 +51,15 @@ proof_bindings:                 # optional provenance metadata
 
 Provenance lives in `proof_bindings`; the contract stays semantic.
 
+- Every `required_proofs[].symbol_id` must name an existing `symbol` entity,
+  or `kb_check` reports `proof-contract-symbols`. Create the symbols first
+  (`kb_upsert`, narrow method-level granularity, never a `type-shape`
+  symbol): a production symbol `implements` the requirement and is
+  `covered_by` the test; an executable test symbol is `executable_for` it.
+- `proof_bindings[].source_file`, when set, must equal the named symbol's
+  `sourceFile`: for a production symbol that is the production file, not the
+  spec file that exercises it. Omit it when unsure.
+
 ## Integration configuration
 
 `.kb/proof/integrations.json` (`kibi.proof-integration.v1`) is tracked,
@@ -62,12 +71,21 @@ returns `integrationPlan`, a hash-bound `kibi.migration-plan.v2`, plus the
 proposal to the human, then apply the plan with `kb_apply_plan` (or
 `kibi apply-plan --input -`) passing `plan`, `approvedPlanHash` (the plan's
 `planHash`) and `approvedActionIds`. Once the file exists, a create plan is
-refused; `kibi proof inspect --update <id> --json` plans adding or replacing
-one named integration.
+refused (`status: error`, `MIGRATION_PLAN_REFUSED`, `data.outcome: refused`;
+nothing is written); `kibi proof inspect --update <id> --json` plans adding or
+replacing one named integration.
 
 - `producer: command` — Kibi synthesizes the envelope from the process
   outcome; obligations are bound with `aggregate_run` provenance and the
-  single process invocation counts as the known first attempt.
+  single process invocation counts as the known first attempt. The run is
+  judged as a whole: any failing test in it fails every obligation of every
+  test that names the integration, so a suite with unrelated failures proves
+  nothing. Narrow the command to the proof-bearing tests with
+  `kibi proof inspect --update <id> --command "<command>" --json` (without
+  `--command` the proposal is the `package.json` `test` script or the
+  detected runner again), or make the run attributable per test: have the
+  command write a `kibi.proof-test-report.v1` to the path in
+  `KIBI_PROOF_TEST_REPORT` so each test is judged by its own steps.
 - `producer: playwright` (or custom) — the child emits `kibi.proof-run.v1`
   itself (bundled reporter: `kibi-cli/playwright-reporter`).
 - `producer: junit` / `tap` — Kibi converts the native report at `artifact`
@@ -79,6 +97,29 @@ Cosmetic edits (descriptions, labels) never stale proof. Execution-relevant
 edits (command, artifact, targets, options, bindings, contract) change the
 effective fingerprint and do.
 
+## What counts toward proofProven
+
+A requirement is proven only by its scenarios' tests, and a scenario test
+counts only when it is an **end-to-end** test with a valid, fresh, passing
+receipt for the current snapshot.
+
+- The scope comes from the test entity's `verification_scope`
+  (`end_to_end`, `integration`, `unit`), never from the integration id or the
+  producer. Without `verification_scope`, a test tagged `e2e` (or whose
+  `source` path contains `e2e`) counts as end-to-end; anything else is
+  `unknown` scope.
+- A `unit` or `integration` receipt is still recorded on the test entity, but
+  it does not move `proofProven` for a behavioural requirement: the
+  requirement keeps the `missing_passing_e2e` gap in `proofGaps`. The one
+  exception is a scenario whose specifying requirements are all grounded only
+  in component-scope UI predicates (`ui_pattern`, `same_pattern`,
+  `pattern_marker`); a unit or integration test that renders the component
+  may prove it.
+- `coverage_depth` (`kb_coverage`, `kb_find_gaps`) follows the test's
+  authored `status` (`passing`) and scope, not its receipts: a passing
+  receipt does not change it, and a `passing` status without a fresh receipt
+  proves nothing.
+
 ## Attempt semantics (factual, never optimistic)
 
 - `attempts: {status: "complete", entries: [...]}` — known history; the