kibi-opencode 0.13.0 → 0.15.0

package/dist/kb-freshness-state.d.ts

@@ -0,0 +1,62 @@
+/**
+ * KB freshness state machine, evidence model, and in-memory evidence store.
+ *
+ * This is Wave 1 — the foundation module. No MCP tools, no filesystem or
+ * `.kb/` persistence, no entity mutation. Pure in-memory state.
+ *
+ * @module kb-freshness-state
+ */
+export type KbFreshnessDecision = "updated" | "no-impact" | "deferred" | "failed";
+export type KbFreshnessStateKind = "clean" | "unknown-impact" | "evidence-required" | "updated" | "no-impact-accepted" | "deferred" | "check-failed";
+export interface KbFreshnessEvidence {
+    sessionId?: string;
+    agentIdentity: string;
+    worktree: string;
+    branch: string;
+    fingerprint: string;
+    changedFiles: string[];
+    kbStatus: boolean;
+    sourceLinkedDiscovery: boolean;
+    kbMutation: boolean;
+    kbCheck: boolean;
+    decision?: KbFreshnessDecision;
+    rationale?: string;
+    checkRules?: string[];
+}
+export interface KbFreshnessEvaluation {
+    state: KbFreshnessStateKind;
+    requiresEvidence: boolean;
+    allowsCompletion: boolean;
+    reason: string;
+    missingEvidence: string[];
+}
+/**
+ * Evaluate KB freshness from collected evidence.
+ *
+ * Rules (in priority order):
+ * 1. No changed files → `clean`, allows completion.
+ * 2. Changed files but no decision → `evidence-required`, blocks completion.
+ * 3. `updated` → requires `kbMutation` + `kbCheck`.
+ * 4. `no-impact` → requires `rationale` + `sourceLinkedDiscovery` + `kbCheck`.
+ * 5. `deferred` → blocks completion.
+ * 6. `failed` → `check-failed`, blocks completion.
+ */
+export declare function evaluateKbFreshness(evidence: KbFreshnessEvidence): KbFreshnessEvaluation;
+export interface KbFreshnessScope {
+    sessionId?: string;
+    agentIdentity: string;
+    worktree: string;
+    branch: string;
+    fingerprint: string;
+}
+export interface KbFreshnessEvidenceStore {
+    recordToolEvidence(scope: KbFreshnessScope, toolName: string): void;
+    recordNoImpact(scope: KbFreshnessScope, rationale: string): void;
+    getEvidence(scope: KbFreshnessScope, changedFiles: string[]): KbFreshnessEvidence;
+    resetScope(scope: KbFreshnessScope): void;
+}
+/**
+ * Create an in-memory evidence store scoped by
+ * (sessionId | agentIdentity | worktree | branch | fingerprint).
+ */
+export declare function createKbFreshnessEvidenceStore(): KbFreshnessEvidenceStore;

package/dist/kb-freshness-state.js

@@ -0,0 +1,211 @@
+/**
+ * KB freshness state machine, evidence model, and in-memory evidence store.
+ *
+ * This is Wave 1 — the foundation module. No MCP tools, no filesystem or
+ * `.kb/` persistence, no entity mutation. Pure in-memory state.
+ *
+ * @module kb-freshness-state
+ */
+// ---------------------------------------------------------------------------
+// Evaluation
+// ---------------------------------------------------------------------------
+/**
+ * Evaluate KB freshness from collected evidence.
+ *
+ * Rules (in priority order):
+ * 1. No changed files → `clean`, allows completion.
+ * 2. Changed files but no decision → `evidence-required`, blocks completion.
+ * 3. `updated` → requires `kbMutation` + `kbCheck`.
+ * 4. `no-impact` → requires `rationale` + `sourceLinkedDiscovery` + `kbCheck`.
+ * 5. `deferred` → blocks completion.
+ * 6. `failed` → `check-failed`, blocks completion.
+ */
+export function evaluateKbFreshness(evidence) {
+    // Rule 1: No changed files
+    if (evidence.changedFiles.length === 0) {
+        return {
+            state: "clean",
+            requiresEvidence: false,
+            allowsCompletion: true,
+            reason: "No files changed",
+            missingEvidence: [],
+        };
+    }
+    // Rule 2: No decision recorded yet
+    if (evidence.decision === undefined) {
+        return {
+            state: "evidence-required",
+            requiresEvidence: true,
+            allowsCompletion: false,
+            reason: "Session modified files without KB tool evidence",
+            missingEvidence: [],
+        };
+    }
+    // Rule 5: Deferred
+    if (evidence.decision === "deferred") {
+        return {
+            state: "deferred",
+            requiresEvidence: false,
+            allowsCompletion: false,
+            reason: "KB freshness check was explicitly deferred",
+            missingEvidence: [],
+        };
+    }
+    // Rule 6: Failed
+    if (evidence.decision === "failed") {
+        return {
+            state: "check-failed",
+            requiresEvidence: false,
+            allowsCompletion: false,
+            reason: "KB freshness check failed",
+            missingEvidence: [],
+        };
+    }
+    // Rule 3: Updated
+    if (evidence.decision === "updated") {
+        const missingEvidence = [];
+        if (!evidence.kbMutation) {
+            missingEvidence.push("kbMutation");
+        }
+        if (!evidence.kbCheck) {
+            missingEvidence.push("kbCheck");
+        }
+        if (missingEvidence.length > 0) {
+            return {
+                state: "evidence-required",
+                requiresEvidence: true,
+                allowsCompletion: false,
+                reason: "KB was updated but required evidence (kbMutation, kbCheck) is missing",
+                missingEvidence,
+            };
+        }
+        return {
+            state: "updated",
+            requiresEvidence: false,
+            allowsCompletion: true,
+            reason: "KB updated and verified via kb_check",
+            missingEvidence: [],
+        };
+    }
+    // Rule 4: No-impact
+    if (evidence.decision === "no-impact") {
+        const missingEvidence = [];
+        if (!evidence.rationale || evidence.rationale === "") {
+            missingEvidence.push("rationale");
+        }
+        if (!evidence.sourceLinkedDiscovery) {
+            missingEvidence.push("sourceLinkedDiscovery");
+        }
+        if (!evidence.kbCheck) {
+            missingEvidence.push("kbCheck");
+        }
+        if (missingEvidence.length > 0) {
+            return {
+                state: "evidence-required",
+                requiresEvidence: true,
+                allowsCompletion: false,
+                reason: "No-impact claim needs rationale, sourceLinkedDiscovery, and kbCheck",
+                missingEvidence,
+            };
+        }
+        return {
+            state: "no-impact-accepted",
+            requiresEvidence: false,
+            allowsCompletion: true,
+            reason: "No-impact accepted with rationale and KB check passed",
+            missingEvidence: [],
+        };
+    }
+    // Exhaustive guard — all decision branches handled above
+    const _exhaustive = evidence.decision;
+    throw new Error(`Unexpected decision: ${_exhaustive}`);
+}
+/**
+ * Map of tool names → evidence side effects.
+ * Each entry lists the evidence fields to set when that tool is used.
+ */
+const TOOL_EFFECTS = {
+    kb_status: ["kbStatus"],
+    kb_search: ["sourceLinkedDiscovery"],
+    kb_query: ["sourceLinkedDiscovery"],
+    kb_graph: ["sourceLinkedDiscovery"],
+    kb_find_gaps: ["sourceLinkedDiscovery"],
+    kb_coverage: ["sourceLinkedDiscovery"],
+    kb_upsert: ["kbMutation"],
+    kb_delete: ["kbMutation"],
+    kb_check: ["kbCheck"],
+};
+function buildScopeKey(scope) {
+    const parts = [
+        scope.sessionId ?? "",
+        scope.agentIdentity,
+        scope.worktree,
+        scope.branch,
+        scope.fingerprint,
+    ];
+    return parts.join("|");
+}
+/**
+ * Create an in-memory evidence store scoped by
+ * (sessionId | agentIdentity | worktree | branch | fingerprint).
+ */
+export function createKbFreshnessEvidenceStore() {
+    const store = new Map();
+    function getOrCreate(scope) {
+        const key = buildScopeKey(scope);
+        if (!store.has(key)) {
+            store.set(key, {
+                kbStatus: false,
+                sourceLinkedDiscovery: false,
+                kbMutation: false,
+                kbCheck: false,
+            });
+        }
+        return store.get(key);
+    }
+    return {
+        recordToolEvidence(scope, toolName) {
+            const record = getOrCreate(scope);
+            const effects = TOOL_EFFECTS[toolName];
+            if (!effects) {
+                return;
+            }
+            for (const field of effects) {
+                if (field === "kbMutation") {
+                    record.kbMutation = true;
+                    record.decision = "updated";
+                }
+                else {
+                    record[field] = true;
+                }
+            }
+        },
+        recordNoImpact(scope, rationale) {
+            const record = getOrCreate(scope);
+            record.decision = "no-impact";
+            record.rationale = rationale;
+        },
+        getEvidence(scope, changedFiles) {
+            const record = getOrCreate(scope);
+            return {
+                ...(scope.sessionId ? { sessionId: scope.sessionId } : {}),
+                agentIdentity: scope.agentIdentity,
+                worktree: scope.worktree,
+                branch: scope.branch,
+                fingerprint: scope.fingerprint,
+                changedFiles,
+                kbStatus: record.kbStatus,
+                sourceLinkedDiscovery: record.sourceLinkedDiscovery,
+                kbMutation: record.kbMutation,
+                kbCheck: record.kbCheck,
+                ...(record.decision !== undefined ? { decision: record.decision } : {}),
+                ...(record.rationale !== undefined ? { rationale: record.rationale } : {}),
+                ...(record.checkRules !== undefined ? { checkRules: record.checkRules } : {}),
+            };
+        },
+        resetScope(scope) {
+            const key = buildScopeKey(scope);
+            store.delete(key);
+        },
+    };
+}

package/dist/kibi-checkpoint-runner.d.ts

@@ -0,0 +1,83 @@
+import { type KibiConfig } from "./config.js";
+import { type EnforcementLifecycleEvent, type PolicyLinkedEntityResult } from "./enforcement-policy.js";
+import type { E2eCoverageSignal } from "./e2e-coverage-signals.js";
+import type { PathKind } from "./path-kind.js";
+import { type CheckRunner, type SyncRunMetadata, type SyncRunner, type TimeoutHandle } from "./scheduler.js";
+import type { WorkContext } from "./work-context-resolver.js";
+export interface KibiCheckpointContext {
+    workContext: WorkContext;
+    config?: KibiConfig;
+    filePath?: string;
+    checkRules?: string[] | undefined;
+    maintenanceDegraded?: boolean;
+    hardGuidanceText?: string | null;
+    lifecycleEvents?: EnforcementLifecycleEvent[];
+    pathKinds?: PathKind[];
+    linkedEntityResults?: PolicyLinkedEntityResult[];
+    e2eSignals?: E2eCoverageSignal[];
+}
+export interface KibiCheckpointRunnerOptions {
+    config?: KibiConfig;
+    runSync?: SyncRunner;
+    runCheck?: CheckRunner;
+    onRunComplete?: (meta: SyncRunMetadata) => void;
+    timeoutMs?: number;
+    setTimeoutFn?: (fn: () => void, ms: number) => TimeoutHandle;
+    clearTimeoutFn?: (handle: TimeoutHandle) => void;
+}
+export interface KibiCheckpointMetadata {
+    fingerprint: string;
+    scopeKey: string;
+    worktree: string;
+    branch: string;
+    sessionId?: string;
+    agentIdentity: string;
+    guidanceRendered?: boolean;
+    guidanceText?: string;
+    sync?: SyncRunMetadata;
+    reason?: string;
+    timeoutMs?: number;
+    checkRules?: string[] | undefined;
+    restoreInstructions?: string;
+}
+export type KibiCheckpointRequestResult = {
+    kind: "requested";
+    metadata: KibiCheckpointMetadata;
+} | {
+    kind: "skip";
+    metadata: KibiCheckpointMetadata;
+} | {
+    kind: "hard_block";
+    metadata: KibiCheckpointMetadata;
+};
+export type KibiCheckpointRunResult = {
+    kind: "passed";
+    metadata: KibiCheckpointMetadata;
+} | {
+    kind: "hard_block";
+    metadata: KibiCheckpointMetadata;
+} | {
+    kind: "skip";
+    metadata: KibiCheckpointMetadata;
+};
+export declare class KibiCheckpointRunner {
+    private readonly config;
+    private readonly runSync;
+    private readonly runCheck;
+    private readonly onRunComplete;
+    private readonly timeoutMs;
+    private readonly setTimeoutFn;
+    private readonly clearTimeoutFn;
+    private readonly requested;
+    private readonly passed;
+    private readonly passedScopeKeysByFingerprint;
+    constructor(options?: KibiCheckpointRunnerOptions);
+    requestCheckpoint(context: KibiCheckpointContext, fingerprint: string): KibiCheckpointRequestResult;
+    isCheckpointPassed(fingerprint: string, context?: KibiCheckpointContext): boolean;
+    runCheckpoint(context: KibiCheckpointContext, fingerprint: string): Promise<KibiCheckpointRunResult>;
+    private baseMetadata;
+    private scopeKey;
+    private renderHardGuidance;
+    private withTimeout;
+    private recordPassed;
+}

package/dist/kibi-checkpoint-runner.js

@@ -0,0 +1,254 @@
+// implements REQ-opencode-worktree-hard-enforcement-v1
+import { DEFAULTS } from "./config.js";
+import { buildEnforcementScopeKey } from "./enforcement-scope.js";
+import { computeEnforcementPolicy, } from "./enforcement-policy.js";
+import { createSyncScheduler, } from "./scheduler.js";
+const HARD_CHECKPOINT_TIMEOUT_MS = 30_000;
+const CHECKPOINT_REASON = "smart-enforcement.checkpoint";
+const NO_E2E_SIGNAL = {
+    level: "none",
+    evidence: [],
+    reminderText: null,
+};
+// implements REQ-opencode-worktree-hard-enforcement-v1
+export class KibiCheckpointRunner {
+    config;
+    runSync;
+    runCheck;
+    onRunComplete;
+    timeoutMs;
+    setTimeoutFn;
+    clearTimeoutFn;
+    requested = new Map();
+    passed = new Map();
+    passedScopeKeysByFingerprint = new Map();
+    constructor(options = {}) {
+        this.config = options.config;
+        this.runSync = options.runSync;
+        this.runCheck = options.runCheck;
+        this.onRunComplete = options.onRunComplete;
+        this.timeoutMs = options.timeoutMs ?? HARD_CHECKPOINT_TIMEOUT_MS;
+        this.setTimeoutFn = options.setTimeoutFn ?? setTimeout;
+        this.clearTimeoutFn = options.clearTimeoutFn ?? clearTimeout;
+    }
+    // implements REQ-opencode-worktree-hard-enforcement-v1
+    requestCheckpoint(context, fingerprint) {
+        const normalizedFingerprint = normalizeFingerprint(fingerprint);
+        const metadata = this.baseMetadata(context, normalizedFingerprint);
+        if (!context.workContext.isAuthoritative) {
+            return {
+                kind: "skip",
+                metadata: { ...metadata, reason: "non_authoritative" },
+            };
+        }
+        const guidanceText = this.renderHardGuidance(context);
+        if (!guidanceText) {
+            return {
+                kind: "hard_block",
+                metadata: {
+                    ...metadata,
+                    guidanceRendered: false,
+                    reason: "hard_guidance_not_rendered",
+                },
+            };
+        }
+        const requested = {
+            guidanceRendered: true,
+            metadata: {
+                ...metadata,
+                guidanceRendered: true,
+                guidanceText,
+            },
+        };
+        this.requested.set(metadata.scopeKey, requested);
+        return { kind: "requested", metadata: requested.metadata };
+    }
+    // implements REQ-opencode-worktree-hard-enforcement-v1
+    isCheckpointPassed(fingerprint, context) {
+        const normalizedFingerprint = normalizeFingerprint(fingerprint);
+        if (context) {
+            return this.passed.has(this.scopeKey(context, normalizedFingerprint));
+        }
+        return (this.passedScopeKeysByFingerprint.get(normalizedFingerprint)?.size ?? 0) > 0;
+    }
+    // implements REQ-opencode-worktree-hard-enforcement-v1
+    async runCheckpoint(context, fingerprint) {
+        const normalizedFingerprint = normalizeFingerprint(fingerprint);
+        const metadata = this.baseMetadata(context, normalizedFingerprint);
+        if (!context.workContext.isAuthoritative) {
+            return {
+                kind: "skip",
+                metadata: { ...metadata, reason: "non_authoritative" },
+            };
+        }
+        if (context.maintenanceDegraded === true) {
+            return {
+                kind: "hard_block",
+                metadata: {
+                    ...metadata,
+                    reason: "maintenance_degraded",
+                    restoreInstructions: "Restore Kibi maintenance for this authoritative root before continuing: ensure sync is enabled and configured KB targets resolve, then retry the hard checkpoint.",
+                },
+            };
+        }
+        const request = this.requested.get(metadata.scopeKey);
+        if (!request?.guidanceRendered) {
+            return {
+                kind: "hard_block",
+                metadata: {
+                    ...metadata,
+                    guidanceRendered: false,
+                    reason: "checkpoint_not_requested",
+                },
+            };
+        }
+        const completions = [];
+        const scheduler = createSyncScheduler({
+            worktree: context.workContext.worktreeRoot,
+            config: context.config ?? this.config ?? DEFAULTS,
+            ...(this.runSync ? { runSync: this.runSync } : {}),
+            ...(this.runCheck ? { runCheck: this.runCheck } : {}),
+            onRunComplete: (meta) => {
+                completions.push(meta);
+                this.onRunComplete?.(meta);
+            },
+        });
+        try {
+            scheduler.scheduleSync(CHECKPOINT_REASON, context.filePath, normalizedCheckRules(context));
+            const outcome = await this.withTimeout(scheduler.flush());
+            if (outcome === "timeout") {
+                scheduler.dispose();
+                return {
+                    kind: "hard_block",
+                    metadata: {
+                        ...request.metadata,
+                        reason: "timeout",
+                        timeoutMs: this.timeoutMs,
+                        checkRules: normalizedCheckRules(context),
+                    },
+                };
+            }
+            const sync = completions[completions.length - 1];
+            if (!sync) {
+                return {
+                    kind: "hard_block",
+                    metadata: {
+                        ...request.metadata,
+                        reason: "sync_not_run",
+                        checkRules: normalizedCheckRules(context),
+                    },
+                };
+            }
+            const failureReason = checkpointFailureReason(sync, normalizedCheckRules(context));
+            if (failureReason) {
+                return {
+                    kind: "hard_block",
+                    metadata: {
+                        ...request.metadata,
+                        sync,
+                        reason: failureReason,
+                        checkRules: normalizedCheckRules(context),
+                    },
+                };
+            }
+            const passedMetadata = {
+                ...request.metadata,
+                sync,
+                checkRules: normalizedCheckRules(context),
+            };
+            this.recordPassed(passedMetadata);
+            return { kind: "passed", metadata: passedMetadata };
+        }
+        finally {
+            scheduler.dispose();
+        }
+    }
+    baseMetadata(context, fingerprint) {
+        const workContext = context.workContext;
+        return {
+            fingerprint,
+            scopeKey: this.scopeKey(context, fingerprint),
+            worktree: workContext.worktreeRoot,
+            branch: workContext.branch,
+            ...(workContext.sessionId !== undefined
+                ? { sessionId: workContext.sessionId }
+                : {}),
+            agentIdentity: workContext.agentIdentity,
+        };
+    }
+    scopeKey(context, fingerprint) {
+        return buildEnforcementScopeKey({
+            sessionId: context.workContext.sessionId,
+            agentIdentity: context.workContext.agentIdentity,
+            worktreeRoot: context.workContext.worktreeRoot,
+            branch: context.workContext.branch,
+            dirtyRelevantFingerprint: fingerprint,
+        });
+    }
+    renderHardGuidance(context) {
+        if (typeof context.hardGuidanceText === "string") {
+            const trimmed = context.hardGuidanceText.trim();
+            return trimmed.length > 0 ? context.hardGuidanceText : null;
+        }
+        const policy = computeEnforcementPolicy({
+            resolvedContext: context.workContext,
+            effectiveMode: "hard",
+            lifecycleEvents: context.lifecycleEvents ?? [defaultLifecycleEvent(context)],
+            pathKinds: context.pathKinds ?? ["code"],
+            linkedEntityResults: context.linkedEntityResults ?? [
+                { ids: [], source: "none" },
+            ],
+            e2eSignals: context.e2eSignals ?? [NO_E2E_SIGNAL],
+            checkpointEvidence: false,
+            posture: context.workContext.posture,
+        });
+        return policy.kind === "hard_block" ? policy.text : null;
+    }
+    async withTimeout(promise) {
+        let timeoutHandle;
+        const timeout = new Promise((resolve) => {
+            timeoutHandle = this.setTimeoutFn(() => resolve("timeout"), this.timeoutMs);
+        });
+        const result = await Promise.race([
+            promise.then(() => "done"),
+            timeout,
+        ]);
+        if (timeoutHandle !== undefined) {
+            this.clearTimeoutFn(timeoutHandle);
+        }
+        return result;
+    }
+    recordPassed(metadata) {
+        this.passed.set(metadata.scopeKey, metadata);
+        const existing = this.passedScopeKeysByFingerprint.get(metadata.fingerprint);
+        if (existing) {
+            existing.add(metadata.scopeKey);
+            return;
+        }
+        this.passedScopeKeysByFingerprint.set(metadata.fingerprint, new Set([metadata.scopeKey]));
+    }
+}
+function normalizeFingerprint(fingerprint) {
+    const trimmed = fingerprint.trim();
+    return trimmed.length > 0 ? trimmed : "clean";
+}
+function normalizedCheckRules(context) {
+    return context.checkRules && context.checkRules.length > 0
+        ? [...context.checkRules]
+        : undefined;
+}
+function defaultLifecycleEvent(context) {
+    return {
+        normalizedPath: context.filePath ?? context.workContext.repoRelativePath ?? "<unknown>",
+        lifecycle: "edited",
+    };
+}
+function checkpointFailureReason(sync, checkRules) {
+    if (sync.exitCode !== 0) {
+        return "sync_failed";
+    }
+    if (checkRules && checkRules.length > 0 && sync.checkExitCode !== 0) {
+        return "check_failed";
+    }
+    return null;
+}

package/dist/meaningful-change-classifier.d.ts

@@ -0,0 +1,30 @@
+import type { PathKind } from "./path-kind.js";
+import type { FileLifecycle } from "./file-operation-state.js";
+import type { RiskClass } from "./risk-classifier.js";
+/**
+ * Classification for whether a file change requires KB freshness evidence.
+ *
+ * - "requires-kb-evidence": The change is meaningful for KB freshness — the KB
+ *   snapshot should be considered stale and needs a re-sync.
+ * - "advisory": The change is low-risk (lockfiles, docs-only) — advisory only.
+ * - "ignored": The change is in a build artifact or third-party path — no KB
+ *   impact.
+ */
+export type MeaningfulChangeClass = "requires-kb-evidence" | "advisory" | "ignored";
+/**
+ * Classify whether a file change requires KB freshness evidence.
+ *
+ * Rules (first match wins):
+ * 1. Ignored paths (build artifacts, vendor dirs) → `ignored`
+ * 2. Advisory paths (lockfiles) → `advisory`
+ * 3. Meaningful pathKinds (code, requirements, KB docs, etc.) → `requires-kb-evidence`
+ * 4. Risk-based upgrade (behavior/traceability/req_policy candidates) → `requires-kb-evidence`
+ * 5. `safe_docs_only` risk + `unknown` pathKind → `advisory`
+ * 6. Default → `requires-kb-evidence` (safety default)
+ */
+export declare function classifyMeaningfulChange(params: {
+    normalizedPath: string;
+    pathKind: PathKind;
+    lifecycle: FileLifecycle;
+    riskClass?: RiskClass;
+}): MeaningfulChangeClass;