kibi-cli 2.3.0 → 2.5.0

package/dist/runtime/detached-snapshot.js

@@ -0,0 +1,92 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+import { detachedHeadWriteRefusal, resolveBranchAttachment, resolveReadBranchAttachment, } from "../utils/branch-resolver.js";
+/** Envelope diagnostic code reported while a detached snapshot is attached. */
+// implements REQ-branch-store-recovery-v4
+export const DETACHED_HEAD_READ_ONLY_CODE = "detached_head_read_only";
+/** True when an operation declares a KB or workspace write. */
+// implements REQ-branch-store-recovery-v4
+export function declaresWriteEffect(effects) {
+    return effects.some((effect) => effect === "kb-write" || effect === "workspace-write");
+}
+/**
+ * Compile (or incrementally refresh) the read-only snapshot of a detached
+ * checkout. The snapshot store is a cache of the checkout's tracked sources:
+ * refreshing it never touches a branch KB or an authored file.
+ */
+// implements REQ-branch-store-recovery-v4
+export async function refreshDetachedSnapshot(workspaceRoot, attachment) {
+    const { syncCommand } = await import("../commands/sync.js");
+    try {
+        await syncCommand({
+            workspaceRoot,
+            detachedSnapshot: attachment,
+            quiet: true,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to compile the read-only snapshot for this detached HEAD: ${message}`);
+    }
+}
+/**
+ * Resolve the branch attachment an operation may use.
+ *
+ * Writes keep the exact-branch contract and receive an actionable refusal on
+ * a detached HEAD. Reads on a detached HEAD that no single branch points at
+ * attach a freshly compiled read-only snapshot of the checkout.
+ */
+// implements REQ-branch-store-recovery-v4
+export async function resolveOperationAttachment(workspaceRoot, spec) {
+    if (declaresWriteEffect(spec.effects)) {
+        const attachment = resolveBranchAttachment(workspaceRoot);
+        if ("error" in attachment && attachment.code === "DETACHED_HEAD") {
+            return {
+                error: detachedHeadWriteRefusal(spec.name, workspaceRoot),
+                code: "DETACHED_HEAD",
+            };
+        }
+        return attachment;
+    }
+    const attachment = resolveReadBranchAttachment(workspaceRoot);
+    if (!("error" in attachment) &&
+        attachment.readOnly !== undefined &&
+        spec.effects.includes("kb-read")) {
+        await refreshDetachedSnapshot(workspaceRoot, attachment);
+    }
+    return attachment;
+}
+/** The envelope diagnostic for an operation answered from a snapshot. */
+// implements REQ-branch-store-recovery-v4
+export function detachedReadOnlyDiagnostic(attachment) {
+    const readOnly = attachment?.readOnly;
+    if (attachment === undefined || readOnly === undefined)
+        return undefined;
+    return {
+        code: DETACHED_HEAD_READ_ONLY_CODE,
+        severity: "warning",
+        message: readOnly.notice,
+        detail: {
+            head: readOnly.head,
+            branchesAtHead: readOnly.branchesAtHead,
+            kbBranch: attachment.kbBranch,
+            storePath: attachment.storePath,
+            writes: "refused",
+        },
+    };
+}

package/dist/schemas/entity.schema.json

@@ -478,6 +478,51 @@
         "text_ref": {
             "type": "string"
         },
+        "origin": {
+            "type": "object",
+            "required": [
+                "kind"
+            ],
+            "properties": {
+                "kind": {
+                    "type": "string",
+                    "enum": [
+                        "human",
+                        "agent",
+                        "migration",
+                        "import"
+                    ],
+                    "description": "Who authored the entity: human, agent, migration (backfilled by kibi migrate) or import."
+                },
+                "ref": {
+                    "type": "string",
+                    "minLength": 1,
+                    "pattern": "\\S",
+                    "description": "Source reference for the authored content: URL, document path, ticket, commit or conversation id."
+                },
+                "approved_by": {
+                    "type": "string",
+                    "minLength": 1,
+                    "pattern": "\\S",
+                    "description": "The person who reviewed and approved this entity's content. Distinct from the requirement-level approved_by of an exception."
+                },
+                "recorded_at": {
+                    "type": "string",
+                    "pattern": "^\\d{4}-\\d{2}-\\d{2}(?:[T ]\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d+)?)?(?:Z|[+-]\\d{2}:?\\d{2})?)?$",
+                    "description": "ISO-8601 time the provenance was recorded."
+                }
+            },
+            "additionalProperties": false
+        },
+        "expects": {
+            "type": "string",
+            "enum": [
+                "success",
+                "rejection",
+                "error"
+            ],
+            "description": "Scenario-only. The scenario's intended outcome. A scenario that expects success and assumes (via `assumes` facts) a value a current requirement forbids fails the scenario-feasibility check."
+        },
         "proof_exempt": {
             "type": "boolean",
             "description": "Requirement-only. Marks a current requirement as intentionally outside E2E-proof scope; requires proof_exempt_reason."
@@ -487,6 +532,33 @@
             "minLength": 1,
             "description": "Requirement-only. Required when proof_exempt is true; surfaces as the applicability reason in coverage rows."
         },
+        "approved_by": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "\\S",
+            "description": "Requirement-only. The human who approved this exception requirement. An exception (a requirement that exempts another and is specified_by a scenario) makes that success scenario feasible only when approved_by is set."
+        },
+        "approval_ref": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Requirement-only. Optional reference to the approval decision record (ticket, ADR or review link) for an exception requirement."
+        },
+        "rationale": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "\\S",
+            "description": "Requirement-only. Why the requirement exists, in one or two sentences from whoever stated the intent. Explanation only: it is not part of the checked meaning."
+        },
+        "exempts_claims": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": {
+                "type": "string",
+                "pattern": "^CLAIM-[A-F0-9]{16}$"
+            },
+            "description": "Requirement-only. Narrows an exception requirement to individual clauses: the claim keys (from logic_claims) of the requirement it exempts whose constraints it waives. Without it the exception waives the whole exempted requirement."
+        },
         "semantic_text": {
             "type": "string",
             "description": "Requirement-only authored prose whose exact UTF-8 bytes anchor the semantic inventory without replacing text_ref evidence."
@@ -1155,6 +1227,15 @@
                 "type": "string"
             }
         },
+        "key_arguments": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": {
+                "type": "string",
+                "minLength": 1
+            }
+        },
         "aliases": {
             "type": "array",
             "items": {
@@ -1380,6 +1461,11 @@
                                 "argument_descriptions"
                             ]
                         },
+                        {
+                            "required": [
+                                "key_arguments"
+                            ]
+                        },
                         {
                             "required": [
                                 "aliases"
@@ -1546,11 +1632,47 @@
                             "required": [
                                 "proof_exempt_reason"
                             ]
+                        },
+                        {
+                            "required": [
+                                "approved_by"
+                            ]
+                        },
+                        {
+                            "required": [
+                                "approval_ref"
+                            ]
+                        },
+                        {
+                            "required": [
+                                "rationale"
+                            ]
+                        },
+                        {
+                            "required": [
+                                "exempts_claims"
+                            ]
                         }
                     ]
                 }
             }
         },
+        {
+            "if": {
+                "properties": {
+                    "type": {
+                        "const": "scenario"
+                    }
+                }
+            },
+            "else": {
+                "not": {
+                    "required": [
+                        "expects"
+                    ]
+                }
+            }
+        },
         {
             "if": {
                 "anyOf": [

package/dist/search-answer.d.ts

@@ -0,0 +1,157 @@
+import type { IntentSearchMatch } from "./intent-search.js";
+import type { PrologPort } from "./public/operations/runtime-types.js";
+/**
+ * The answer layer turns ranked matches into what an agent asking "what
+ * governs this?" needs: the current requirements that apply, why (ADRs, with
+ * an excerpt of their decision), what must stay true (linked facts), what
+ * verifies it (scenarios and tests), what the existing checks say about it
+ * (contradiction and scenario-feasibility witnesses, exceptions, and what is
+ * still unknown), and the KB snapshot the answer was computed from.
+ * Superseded or deprecated requirements are listed separately so they are
+ * never read as current policy, and observation facts are labelled as notes,
+ * not rules. Tests are collected through the canonical
+ * REQ -specified_by-> SCEN -verified_by-> TEST path as well as direct
+ * requirement links, and each says how it was reached. Graph links are
+ * discovery, not proof, and a verdict of `none` means no check named the
+ * requirement, not that it is proven.
+ */
+export type SearchAnswerEntity = Readonly<{
+    id: string;
+    title: string;
+    status?: string;
+}>;
+/**
+ * A test verifying a governing requirement. `via` is `"direct"` for a test
+ * linked to the requirement itself, or the id of the scenario it verifies.
+ */
+export type SearchAnswerTest = SearchAnswerEntity & Readonly<{
+    via: string;
+}>;
+/** An ADR with the opening of its decision (or rationale) section. */
+export type SearchAnswerRationale = SearchAnswerEntity & Readonly<{
+    source?: string;
+    excerpt?: string;
+}>;
+/** A blocking finding of an existing check that names the requirement. */
+export type SearchAnswerWitness = Readonly<{
+    check: "domain-contradictions" | "scenario-feasibility";
+    status: "contradiction" | "infeasible";
+    /** The other requirement in a contradiction, or the forbidding one. */
+    with?: string;
+    scenario?: string;
+    facts: readonly string[];
+    detail: string;
+}>;
+/**
+ * What the checks could not decide for the requirement: rule overlaps they
+ * could not classify, scenarios whose feasibility is unknown, propositions
+ * still ambiguous or ontology gaps, a missing clause ledger, or a verdict
+ * that could not be computed.
+ */
+export type SearchAnswerUnknown = Readonly<{
+    kind: "contradiction_unresolved" | "feasibility_unknown" | "unresolved_proposition" | "analysis_incomplete" | "verdict_unavailable";
+    detail: string;
+    entities: readonly string[];
+}>;
+export type SearchAnswerVerdict = Readonly<{
+    /**
+     * The worst finding: `contradiction` or `infeasible` when a blocking
+     * witness exists, `unknown` when only unknowns remain, `none` when no
+     * check named the requirement (absence of a witness is not proof).
+     */
+    status: "contradiction" | "infeasible" | "unknown" | "none";
+    witnesses: readonly SearchAnswerWitness[];
+}>;
+/** A requirement that `exempts` the governing one. */
+export type SearchAnswerException = SearchAnswerEntity & Readonly<{
+    approvedBy?: string;
+}>;
+export type SearchAnswerRequirement = SearchAnswerEntity & Readonly<{
+    score: number;
+    via: string;
+    facts: readonly (SearchAnswerEntity & {
+        factKind?: string;
+    })[];
+    scenarios: readonly SearchAnswerEntity[];
+    tests: readonly SearchAnswerTest[];
+    adrs: readonly SearchAnswerEntity[];
+    verdict: SearchAnswerVerdict;
+    exceptions: readonly SearchAnswerException[];
+    unknowns: readonly SearchAnswerUnknown[];
+}>;
+/** The KB the answer was computed from. */
+export type SearchAnswerScope = Readonly<{
+    branch: string | null;
+    snapshotId: string;
+    syncedAt: string | null;
+}>;
+export type SearchAnswer = Readonly<{
+    version: "kibi.search-answer.v1";
+    governing: readonly SearchAnswerRequirement[];
+    rationale: readonly SearchAnswerRationale[];
+    notGoverning: readonly (SearchAnswerEntity & {
+        supersededBy?: string;
+    })[];
+    observations: readonly SearchAnswerEntity[];
+    scope: SearchAnswerScope;
+    truncated: boolean;
+    note: string;
+}>;
+export type SearchAnswerOptions = Readonly<{
+    /** Root that ADR sources resolve against; without it no excerpts. */
+    workspaceRoot?: string;
+    /** The Git branch identity of the attached KB. */
+    branch?: string | null;
+}>;
+export declare const SEARCH_ANSWER_LIMITS: {
+    readonly seeds: 10;
+    readonly governing: 5;
+    readonly perRequirement: 4;
+    readonly rationale: 3;
+    readonly notGoverning: 5;
+    readonly observations: 3;
+    /** Entity rows loaded per answer, the matched seeds included. */
+    readonly entityLoads: 70;
+    readonly maxBytes: 16384;
+    /** Title length (characters) kept when an answer must shrink to fit. */
+    readonly titleChars: 160;
+    /** Characters of an ADR decision kept as its excerpt. */
+    readonly excerptChars: 280;
+    /** Characters of a witness or unknown detail kept. */
+    readonly detailChars: 240;
+};
+/**
+ * The opening sentences of an ADR's Decision section (falling back to
+ * Rationale, then to the first prose paragraph), as plain text of at most
+ * `maxChars` characters.
+ */
+export declare function adrExcerpt(body: string, maxChars?: number): string | undefined;
+type RawVerdict = Readonly<{
+    id?: unknown;
+    error?: unknown;
+    contradictions?: unknown;
+    scenarios?: unknown;
+    forbids?: unknown;
+    inventory?: unknown;
+}>;
+/** Project the Prolog verdict of one requirement onto the answer fields. */
+export declare function projectVerdict(raw: RawVerdict | undefined, perRequirement?: number): {
+    verdict: SearchAnswerVerdict;
+    unknowns: SearchAnswerUnknown[];
+    truncated: boolean;
+};
+export declare function buildSearchAnswer(prolog: Pick<PrologPort, "query">, matches: readonly IntentSearchMatch[], options?: SearchAnswerOptions): Promise<SearchAnswer>;
+/**
+ * Hold the whole answer under `maxBytes`, marking it truncated when anything
+ * is cut. In order: long titles, excerpts and details are clipped; ADR
+ * excerpts are dropped, last rationale entry first; the least relevant
+ * governing requirements are dropped;
+ * list items are dropped (notes and side lists before the remaining
+ * requirement's own lists, its verdict witnesses last); then the remaining
+ * requirement's title and `via` are clipped. A verdict keeps its status when
+ * its witnesses are dropped. If even that cannot fit, the requirement itself
+ * is dropped.
+ */
+export declare function fitSearchAnswer(answer: SearchAnswer, maxBytes?: number): SearchAnswer;
+export {};
+//# sourceMappingURL=search-answer.d.ts.map

package/dist/search-answer.d.ts.map

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