kibi-opencode 0.13.0 → 0.14.0

package/README.md

@@ -26,11 +26,11 @@ The plugin now uses a posture-aware, low-token smart-enforcement model before em
 - **Risk classification**: separates `safe_docs_only`, `safe_test_only`, `kb_doc_structural`, `req_policy_candidate`, `behavior_candidate`, `traceability_candidate`, and `manual_kb_edit`
 - **Source-linked micro-briefs**: risky code edits (`behavior_candidate`, `traceability_candidate`) prepend a concise list of existing Kibi links (e.g., `- Existing Kibi links: REQ-001, REQ-002`) when 1-3 concrete source-linked KB hits are found in `documentation/symbols.yaml`. Skip on cache hit.
 - **Start-task risky cue**: authoritative risky edits also add a compact `/brief-kibi` cue so agents can start with an explicit Kibi briefing before acting, while staying inside the same single prompt block and token budget.
-- **Effective mode gating**: `strict` is only possible for `root_active` and `hybrid_root_plus_vendored` when `requireRootKbForStrict` is enabled; `maintenanceDegraded` overrides everything back to `advisory`
+- **Effective mode gating**: `advisory` (default) never blocks; `strict` escalates checks and reminders for `root_active` and `hybrid_root_plus_vendored` postures when `requireRootKbForStrict` is enabled; `hard` fails closed for authoritative roots and linked git worktrees, injecting a stop-state with MCP recovery steps until the Kibi checkpoint passes. `maintenanceDegraded` overrides everything back to `advisory`.
 - **Low-token prompt policy**: docs-only and test-only edits avoid unnecessary discovery prompts; vendored-only repos suppress operational bootstrap nudges; at most one contextual block is injected per prompt (≤120 words, ≤5 bullets)
 - **Completion reminder**: when `completionReminder` is enabled, risky code edits append a single prompt-visible `kb_check` reminder exactly once per cached context
 - **Runtime maintenance overlay**: static `maintenanceDegraded` from posture is merged with a latched runtime overlay (sync disabled/unavailable/failing) so degraded state is consistently reflected in prompts, logs, and mode decisions
-- **Advisory in editor, hard in hooks**: OpenCode guidance remains non-blocking; git hooks and KB validation checks stay the durable enforcement boundary
+- **Three-mode enforcement**: `advisory` by default keeps guidance non-blocking; opt-in `strict` adds elevated validation cues; `hard` blocks the prompt for authoritative workspaces until the checkpoint cycle succeeds. Git hooks and KB validation checks remain the durable enforcement boundary for all modes.
 - **Structured observability**: posture, risk, cache, degraded-mode, targeted-check, and guidance events flow through structured plugin logs
 
 ### Dynamic Contextual Guidance
@@ -176,7 +176,7 @@ PP|| `guidance.dynamic` | boolean | `true` | Enable dynamic contextual guidance
 | `guidance.sessionSummary.enabled` | boolean | `true` | Enable periodic session summary logs |
 | `guidance.sessionSummary.logIntervalMs` | number | `1800000` | Session summary interval (30 min) |
 | `guidance.smartEnforcement.enabled` | boolean | `true` | Enable posture-aware, risk-aware guidance routing |
-| `guidance.smartEnforcement.mode` | string | `"advisory"` | Smart-enforcement mode: `advisory` or `strict` |
+| `guidance.smartEnforcement.mode` | string | `"advisory"` | Smart-enforcement mode: `advisory`, `strict`, or `hard` |
 | `guidance.smartEnforcement.preflightTtlMs` | number | `600000` | Guidance/cache TTL for repeated prompt suppression |
 | `guidance.smartEnforcement.idleResetMs` | number | `1800000` | Idle window before smart-enforcement state resets |
 | `guidance.smartEnforcement.degradedMode` | string | `"warn-once"` | Degraded-mode logging policy: `warn-once` or `structured-only` |
@@ -188,7 +188,7 @@ PP|| `guidance.dynamic` | boolean | `true` | Enable dynamic contextual guidance
 
 Per ADR-016, prompt text injection uses only `experimental.chat.system.transform`. The `chat.params` hook is reserved for model option enrichment (temperature, topP, etc.) and never carries prompt text.
 
-Smart enforcement keeps the plugin advisory-only: prompt injection can warn, explain, or remind, but it does not block the editor. Hard failures still belong to CLI hooks (`pre-commit`) and explicit check commands.
+Smart enforcement is `advisory` by default: prompt injection can warn, explain, or remind without blocking the editor. Opt-in `strict` escalates validation reminders, and `hard` can block the prompt for authoritative roots and linked worktrees until the Kibi checkpoint passes. Hard failures outside the plugin surface still belong to CLI hooks (`pre-commit`) and explicit check commands.
 
 ### Logging Policy
 

package/dist/config.d.ts

@@ -36,7 +36,7 @@ export interface KibiConfig {
         };
         smartEnforcement: {
             enabled: boolean;
-            mode: "advisory" | "strict";
+            mode: "advisory" | "strict" | "hard";
             preflightTtlMs: number;
             idleResetMs: number;
             degradedMode: "warn-once" | "structured-only";

package/dist/config.js

@@ -57,7 +57,7 @@ function readJsonIfExists(filePath) {
         return null;
     }
 }
-// implements REQ-opencode-kibi-plugin-v1
+// implements REQ-opencode-kibi-plugin-v1, REQ-opencode-worktree-hard-enforcement-v1
 export function validateAndMerge(obj) {
     if (!obj || typeof obj !== "object") {
         logger.warn("Config is not an object, using defaults");
@@ -150,7 +150,7 @@ export function validateAndMerge(obj) {
             };
             if (typeof se.enabled === "boolean")
                 out.guidance.smartEnforcement.enabled = se.enabled;
-            if (se.mode === "advisory" || se.mode === "strict")
+            if (se.mode === "advisory" || se.mode === "strict" || se.mode === "hard")
                 out.guidance.smartEnforcement.mode = se.mode;
             if (typeof se.preflightTtlMs === "number")
                 out.guidance.smartEnforcement.preflightTtlMs = se.preflightTtlMs;

package/dist/enforcement-policy.d.ts

@@ -0,0 +1,71 @@
+import type { E2eCoverageSignal } from "./e2e-coverage-signals.js";
+import type { FileLifecycle, ReminderKind } from "./file-operation-state.js";
+import type { PathKind } from "./path-kind.js";
+import type { RepoPosture } from "./repo-posture.js";
+import type { RiskClass } from "./risk-classifier.js";
+import type { EffectiveMode } from "./smart-enforcement.js";
+import type { WorkContext } from "./work-context-resolver.js";
+export interface PolicyLinkedEntityResult {
+    ids: string[];
+    source: "symbols" | "doc-path" | "none";
+}
+export interface EnforcementLifecycleEvent {
+    normalizedPath: string;
+    lifecycle: FileLifecycle;
+}
+export type CheckpointEvidence = boolean | {
+    hasCheckpoint?: boolean;
+    kbSearch?: boolean;
+    sourceFileQuery?: boolean;
+    kbStatus?: boolean;
+    kbCheck?: boolean;
+    kbUpsert?: boolean;
+};
+export interface EnforcementPolicyInput {
+    /** Resolved work context for the current file/prompt cycle. */
+    resolvedContext?: WorkContext | undefined;
+    /** Alias accepted by callers/tests that already carry WorkContext as workContext. */
+    workContext?: WorkContext | undefined;
+    /** Effective enforcement mode after config/posture resolution. */
+    effectiveMode: EffectiveMode;
+    /** Coalesced lifecycle events for this prompt cycle. */
+    lifecycleEvents: EnforcementLifecycleEvent[];
+    /** Path kinds aligned by index with lifecycleEvents. */
+    pathKinds: PathKind[];
+    /** Linked entity lookups aligned by index with lifecycleEvents. */
+    linkedEntityResults?: PolicyLinkedEntityResult[] | undefined;
+    /** Convenience linked-ID-only input aligned by index with lifecycleEvents. */
+    linkedEntityIds?: string[][] | undefined;
+    /** E2e signals aligned by index with lifecycleEvents. */
+    e2eSignals?: E2eCoverageSignal[] | undefined;
+    /** Semantic risk for the current focus event. */
+    currentSemanticRisk?: RiskClass | undefined;
+    /** Whether a Kibi checkpoint already happened in this cycle. */
+    checkpointEvidence?: CheckpointEvidence | undefined;
+    /** Posture fallback when resolvedContext is unavailable. */
+    posture?: RepoPosture | undefined;
+}
+interface EnforcementPolicyResultBase {
+    affectedPaths: string[];
+    dirtyFileCount: number;
+    e2eReminder: string | null;
+    reminderKindsToMark: ReminderKind[];
+}
+export type EnforcementPolicyResult = (EnforcementPolicyResultBase & {
+    kind: "skip_non_authoritative";
+    reason: string;
+    text: null;
+}) | (EnforcementPolicyResultBase & {
+    kind: "advisory_guidance";
+    text: string;
+}) | (EnforcementPolicyResultBase & {
+    kind: "hard_block";
+    text: string;
+    shownPaths: string[];
+    remainingCount: number;
+}) | (EnforcementPolicyResultBase & {
+    kind: "checkpoint_passed";
+    text: null;
+});
+export declare function computeEnforcementPolicy(input: EnforcementPolicyInput): EnforcementPolicyResult;
+export {};

package/dist/enforcement-policy.js

@@ -0,0 +1,269 @@
+const NO_E2E_SIGNAL = {
+    level: "none",
+    evidence: [],
+    reminderText: null,
+};
+const DEFAULT_LINKED_ENTITY_RESULT = {
+    ids: [],
+    source: "none",
+};
+const HARD_BLOCK_PATH_LIMIT = 5;
+const AUTHORITATIVE_POSTURES = new Set([
+    "root_active",
+    "hybrid_root_plus_vendored",
+]);
+const ADVISORY_EDIT_KINDS = new Set([
+    "code",
+    "requirement",
+    "scenario",
+    "test",
+    "adr",
+    "fact",
+    "flag",
+    "event",
+    "symbol",
+    "kb",
+]);
+function normalizeCheckpointEvidence(evidence) {
+    if (typeof evidence === "boolean") {
+        return evidence;
+    }
+    if (!evidence) {
+        return false;
+    }
+    return (evidence.hasCheckpoint === true ||
+        evidence.kbSearch === true ||
+        evidence.sourceFileQuery === true ||
+        evidence.kbStatus === true ||
+        evidence.kbCheck === true ||
+        evidence.kbUpsert === true);
+}
+function isAuthoritative(input) {
+    const context = input.resolvedContext ?? input.workContext;
+    if (context) {
+        return context.isAuthoritative;
+    }
+    return input.posture ? AUTHORITATIVE_POSTURES.has(input.posture) : true;
+}
+function normalizeEvents(input) {
+    return input.lifecycleEvents.map((event, index) => {
+        const linkedEntityResult = input.linkedEntityResults?.[index] ??
+            (input.linkedEntityIds?.[index]
+                ? { ids: input.linkedEntityIds[index] ?? [], source: "symbols" }
+                : DEFAULT_LINKED_ENTITY_RESULT);
+        return {
+            ...event,
+            pathKind: input.pathKinds[index] ?? "unknown",
+            linkedEntityResult,
+            e2eSignal: input.e2eSignals?.[index] ?? NO_E2E_SIGNAL,
+        };
+    });
+}
+function isIgnoredKind(pathKind) {
+    return pathKind === "ignored";
+}
+function isRelevantEvent(event, effectiveMode) {
+    if (isIgnoredKind(event.pathKind)) {
+        return false;
+    }
+    if (effectiveMode === "hard") {
+        return true;
+    }
+    if (event.lifecycle === "created") {
+        return event.pathKind === "code";
+    }
+    if (event.lifecycle === "edited") {
+        return ADVISORY_EDIT_KINDS.has(event.pathKind);
+    }
+    return true;
+}
+function uniqueReminderKinds(events) {
+    const kinds = [];
+    const add = (kind) => {
+        if (!kinds.includes(kind)) {
+            kinds.push(kind);
+        }
+    };
+    for (const event of events) {
+        if (event.lifecycle === "deleted") {
+            add("kibi_delete");
+        }
+        else {
+            add("kibi_write");
+        }
+        if (event.e2eSignal.level !== "none" && event.e2eSignal.reminderText !== null) {
+            add(event.lifecycle === "deleted" ? "e2e_delete" : "e2e_write");
+        }
+    }
+    return kinds;
+}
+function firstE2eReminder(events) {
+    return (events.find((event) => event.e2eSignal.level !== "none" &&
+        event.e2eSignal.reminderText !== null)?.e2eSignal.reminderText ?? null);
+}
+function lifecycleLabel(lifecycle) {
+    switch (lifecycle) {
+        case "created":
+            return "created";
+        case "edited":
+            return "edited";
+        case "deleted":
+            return "deleted";
+    }
+}
+function advisoryText(event) {
+    if (event.lifecycle === "created") {
+        return "- New file detected. Add or update the necessary Kibi entities and traceability before completing this task.";
+    }
+    if (event.lifecycle === "edited") {
+        return `- Edited file detected. Review Kibi traceability for ${event.normalizedPath} before completing this task.`;
+    }
+    const ids = event.linkedEntityResult.ids;
+    if (ids.length > 0) {
+        return `- Deleted file had linked Kibi entities: ${ids.join(", ")}. Update Kibi to keep traceability accurate.`;
+    }
+    return "- Deleted file had no linked Kibi entities. Update Kibi if this removal changes documented behavior or traceability.";
+}
+function collectUnique(values) {
+    const seen = new Set();
+    const result = [];
+    for (const value of values) {
+        if (seen.has(value)) {
+            continue;
+        }
+        seen.add(value);
+        result.push(value);
+    }
+    return result;
+}
+function linkedIdsText(events) {
+    const ids = collectUnique(events.flatMap((event) => event.linkedEntityResult.ids));
+    if (ids.length === 0) {
+        return null;
+    }
+    return `Linked IDs detected: ${ids.join(", ")}.`;
+}
+function e2eEvidenceText(events) {
+    const evidence = collectUnique(events.flatMap((event) => event.e2eSignal.evidence));
+    if (evidence.length === 0) {
+        return null;
+    }
+    return `Existing e2e evidence: ${evidence.join(", ")}.`;
+}
+function hardBlockText(events) {
+    const shownEvents = events.slice(0, HARD_BLOCK_PATH_LIMIT);
+    const shownPaths = shownEvents.map((event) => event.normalizedPath);
+    const remainingCount = Math.max(0, events.length - shownEvents.length);
+    const pathLines = shownEvents.map((event) => {
+        const ids = event.linkedEntityResult.ids;
+        const linkedSuffix = ids.length > 0 ? `; linked: ${ids.join(", ")}` : "";
+        return `- \`${event.normalizedPath}\` (${lifecycleLabel(event.lifecycle)}, ${event.pathKind}${linkedSuffix})`;
+    });
+    if (remainingCount > 0) {
+        pathLines.push(`- +${remainingCount} more dirty files`);
+    }
+    const deletedWithoutLinks = events.some((event) => event.lifecycle === "deleted" && event.linkedEntityResult.ids.length === 0);
+    const representativePath = events[0]?.normalizedPath ?? "<changed-file>";
+    const evidenceNotes = [linkedIdsText(events), e2eEvidenceText(events)].filter((note) => note !== null);
+    const deletionCleanup = deletedWithoutLinks
+        ? "Deleted files without linked IDs still need sourceFile cleanup: use `kb_search` plus `kb_query` with `sourceFile` for the deleted path before deciding whether `kb_upsert` cleanup is needed."
+        : "Use `kb_upsert` when traceability, relationships, or source-linked facts need updates.";
+    return {
+        text: [
+            "🛑 **Hard Kibi checkpoint required**",
+            "Changed relevant files require Kibi verification before continuing:",
+            ...pathLines,
+            ...evidenceNotes,
+            "MCP-only checkpoint instructions:",
+            "- Run `kb_search` to discover impacted requirements, tests, ADRs, and facts.",
+            `- Run \`kb_query\` with \`sourceFile\` (example sourceFile: \"${representativePath}\") for each listed path.`,
+            "- Run `kb_status` if branch or snapshot freshness matters.",
+            `- ${deletionCleanup}`,
+            "- Run `kb_check` before completing the task.",
+        ].join("\n"),
+        shownPaths,
+        remainingCount,
+    };
+}
+// implements REQ-opencode-worktree-hard-enforcement-v1
+export function computeEnforcementPolicy(input) {
+    const allEvents = normalizeEvents(input);
+    const relevantEvents = allEvents.filter((event) => isRelevantEvent(event, input.effectiveMode));
+    const affectedPaths = relevantEvents.map((event) => event.normalizedPath);
+    const e2eReminder = firstE2eReminder(relevantEvents);
+    const reminderKindsToMark = uniqueReminderKinds(relevantEvents);
+    if (relevantEvents.length === 0) {
+        return {
+            kind: "checkpoint_passed",
+            affectedPaths,
+            dirtyFileCount: 0,
+            e2eReminder,
+            reminderKindsToMark,
+            text: null,
+        };
+    }
+    if (input.effectiveMode === "hard") {
+        if (!isAuthoritative(input)) {
+            return {
+                kind: "skip_non_authoritative",
+                reason: "Hard enforcement only applies to authoritative Kibi roots.",
+                affectedPaths,
+                dirtyFileCount: relevantEvents.length,
+                e2eReminder,
+                reminderKindsToMark: [],
+                text: null,
+            };
+        }
+        if (normalizeCheckpointEvidence(input.checkpointEvidence)) {
+            return {
+                kind: "checkpoint_passed",
+                affectedPaths,
+                dirtyFileCount: relevantEvents.length,
+                e2eReminder,
+                reminderKindsToMark,
+                text: null,
+            };
+        }
+        const { text, shownPaths, remainingCount } = hardBlockText(relevantEvents);
+        return {
+            kind: "hard_block",
+            affectedPaths,
+            dirtyFileCount: relevantEvents.length,
+            e2eReminder,
+            reminderKindsToMark,
+            text,
+            shownPaths,
+            remainingCount,
+        };
+    }
+    if (!isAuthoritative(input)) {
+        return {
+            kind: "skip_non_authoritative",
+            reason: "Lifecycle guidance is skipped outside authoritative Kibi roots.",
+            affectedPaths,
+            dirtyFileCount: relevantEvents.length,
+            e2eReminder,
+            reminderKindsToMark: [],
+            text: null,
+        };
+    }
+    const firstRelevantEvent = relevantEvents[0];
+    if (!firstRelevantEvent) {
+        return {
+            kind: "checkpoint_passed",
+            affectedPaths,
+            dirtyFileCount: 0,
+            e2eReminder,
+            reminderKindsToMark,
+            text: null,
+        };
+    }
+    return {
+        kind: "advisory_guidance",
+        affectedPaths,
+        dirtyFileCount: relevantEvents.length,
+        e2eReminder,
+        reminderKindsToMark,
+        text: advisoryText(firstRelevantEvent),
+    };
+}

package/dist/enforcement-scope.d.ts

@@ -0,0 +1,15 @@
+export interface EnforcementScopeInput {
+    sessionId?: string | undefined;
+    agentIdentity?: string | undefined;
+    worktreeRoot: string;
+    branch: string;
+    dirtyRelevantFingerprint: string;
+}
+/**
+ * Build a deterministic scope key for hard-enforcement decisions.
+ */
+export declare function buildEnforcementScopeKey(input: EnforcementScopeInput): string;
+/**
+ * Hash dirty relevant inputs into a stable, order-insensitive fingerprint.
+ */
+export declare function buildDirtyRelevantFingerprint(values: Iterable<string | null | undefined>): string;

package/dist/enforcement-scope.js

@@ -0,0 +1,36 @@
+// implements REQ-opencode-worktree-hard-enforcement-v1
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+function normalizeComponent(value, fallback) {
+    const trimmed = value?.trim();
+    return trimmed && trimmed.length > 0 ? trimmed : fallback;
+}
+/**
+ * Build a deterministic scope key for hard-enforcement decisions.
+ */
+// implements REQ-opencode-worktree-hard-enforcement-v1
+export function buildEnforcementScopeKey(input) {
+    return JSON.stringify({
+        sessionId: normalizeComponent(input.sessionId, "unknown"),
+        agentIdentity: normalizeComponent(input.agentIdentity, "unknown"),
+        worktreeRoot: resolve(input.worktreeRoot),
+        branch: normalizeComponent(input.branch, "unknown"),
+        dirtyRelevantFingerprint: normalizeComponent(input.dirtyRelevantFingerprint, "clean"),
+    });
+}
+/**
+ * Hash dirty relevant inputs into a stable, order-insensitive fingerprint.
+ */
+// implements REQ-opencode-worktree-hard-enforcement-v1
+export function buildDirtyRelevantFingerprint(values) {
+    const normalized = [...values]
+        .map((value) => value?.trim() ?? "")
+        .filter((value) => value.length > 0)
+        .sort();
+    if (normalized.length === 0) {
+        return "clean";
+    }
+    return createHash("sha256")
+        .update(JSON.stringify(normalized))
+        .digest("hex");
+}

package/dist/file-operation-reminders.d.ts

@@ -3,6 +3,9 @@ import type { PathKind } from "./path-kind.js";
 import type { RiskClass } from "./risk-classifier.js";
 import type { ReminderKind } from "./file-operation-state.js";
 import type { E2eCoverageSignal } from "./e2e-coverage-signals.js";
+import { type CheckpointEvidence, type EnforcementLifecycleEvent, type EnforcementPolicyResult } from "./enforcement-policy.js";
+import type { EffectiveMode } from "./smart-enforcement.js";
+import type { WorkContext } from "./work-context-resolver.js";
 export interface LinkedEntityResult {
     ids: string[];
     source: "symbols" | "doc-path" | "none";
@@ -15,10 +18,20 @@ export interface DeriveFileOperationReminderParams {
     e2eSignal: E2eCoverageSignal;
     currentSemanticRisk: RiskClass;
     posture: RepoPosture;
+    effectiveMode?: EffectiveMode;
+    workContext?: WorkContext;
+    resolvedContext?: WorkContext;
+    lifecycleEvents?: EnforcementLifecycleEvent[];
+    pathKinds?: PathKind[];
+    linkedEntityResults?: LinkedEntityResult[];
+    e2eSignals?: E2eCoverageSignal[];
+    checkpointEvidence?: CheckpointEvidence;
 }
 export interface DeriveFileOperationReminderResult {
     lifecycleReminder: string | null;
     e2eReminder: string | null;
     reminderKindsToMark: ReminderKind[];
+    policyDecision: EnforcementPolicyResult["kind"];
+    policyResult: EnforcementPolicyResult;
 }
 export declare function deriveFileOperationReminder(params: DeriveFileOperationReminderParams): DeriveFileOperationReminderResult;

package/dist/file-operation-reminders.js

@@ -1,55 +1,42 @@
-// ── Lifecycle reminder text ─────────────────────────────────────
-const NEW_FILE_REMINDER = "- New file detected. Add or update the necessary Kibi entities and traceability before completing this task.";
-const DELETED_WITH_IDS_REMINDER = (ids) => `- Deleted file had linked Kibi entities: ${ids}. Update Kibi to keep traceability accurate.`;
-const DELETED_NO_IDS_REMINDER = "- Deleted file had no linked Kibi entities. Update Kibi if this removal changes documented behavior or traceability.";
+import { computeEnforcementPolicy, } from "./enforcement-policy.js";
+function addUniqueReminderKind(kinds, kind) {
+    return kinds.includes(kind) ? kinds : [...kinds, kind];
+}
 // ── Main exported function ────────────────────────────────────
 // implements REQ-opencode-file-context-guidance-v1
 export function deriveFileOperationReminder(params) {
-    const { lifecycle, pathKind, linkedEntityResult, e2eSignal, posture, } = params;
-    // Check if posture allows lifecycle reminders
-    const isAuthoritativePosture = posture === "root_active" || posture === "hybrid_root_plus_vendored";
-    // Derive lifecycle reminder
-    let lifecycleReminder = null;
-    const reminderKindsToMark = [];
-    if (isAuthoritativePosture) {
-        if (lifecycle === "created") {
-            // Only emit create reminder for code files (not documentation, not KB docs)
-            if (pathKind === "code") {
-                lifecycleReminder = NEW_FILE_REMINDER;
-                reminderKindsToMark.push("kibi_write");
-            }
-        }
-        else if (lifecycle === "edited") {
-            // No generic lifecycle reminder for edited files
-            // Existing semantic risk guidance remains primary
-        }
-        else if (lifecycle === "deleted") {
-            const ids = linkedEntityResult.ids;
-            if (ids.length > 0) {
-                lifecycleReminder = DELETED_WITH_IDS_REMINDER(ids.join(", "));
-                reminderKindsToMark.push("kibi_delete");
-            }
-            else {
-                lifecycleReminder = DELETED_NO_IDS_REMINDER;
-                reminderKindsToMark.push("kibi_delete");
-            }
-        }
-    }
+    const { normalizedPath, lifecycle, pathKind, linkedEntityResult, e2eSignal, currentSemanticRisk, posture, } = params;
+    const policyResult = computeEnforcementPolicy({
+        resolvedContext: params.resolvedContext,
+        workContext: params.workContext,
+        effectiveMode: params.effectiveMode ?? "advisory",
+        lifecycleEvents: params.lifecycleEvents ?? [{ normalizedPath, lifecycle }],
+        pathKinds: params.pathKinds ?? [pathKind],
+        linkedEntityResults: params.linkedEntityResults ?? [linkedEntityResult],
+        e2eSignals: params.e2eSignals ?? [e2eSignal],
+        currentSemanticRisk,
+        checkpointEvidence: params.checkpointEvidence,
+        posture,
+    });
+    const lifecycleReminder = policyResult.text;
+    let reminderKindsToMark = [...policyResult.reminderKindsToMark];
     // Derive e2e reminder (only when e2e signal exists)
     // E2e reminders are NOT posture-gated - they're always relevant
-    let e2eReminder = null;
+    let e2eReminder = policyResult.e2eReminder;
     if (e2eSignal.level !== "none" && e2eSignal.reminderText !== null) {
         e2eReminder = e2eSignal.reminderText;
         if (lifecycle === "deleted") {
-            reminderKindsToMark.push("e2e_delete");
+            reminderKindsToMark = addUniqueReminderKind(reminderKindsToMark, "e2e_delete");
         }
         else {
-            reminderKindsToMark.push("e2e_write");
+            reminderKindsToMark = addUniqueReminderKind(reminderKindsToMark, "e2e_write");
         }
     }
     return {
         lifecycleReminder,
         e2eReminder,
         reminderKindsToMark,
+        policyDecision: policyResult.kind,
+        policyResult,
     };
 }

package/dist/guidance-cache.d.ts

@@ -3,6 +3,8 @@ import type { RiskClass } from "./risk-classifier.js";
 /**
  * Cache key uniquely identifies a preflight context by combining
  * workspace root, branch, posture, risk class, and file bucket.
+ * Hard-enforcement callers may additionally pass scopeKey to prevent
+ * cross-session/worktree dirty-state cache hits. Advisory callers omit it.
  */
 export interface CacheKey {
     workspaceRoot: string;
@@ -10,6 +12,7 @@ export interface CacheKey {
     posture: RepoPosture;
     riskClass: RiskClass;
     fileBucket: string;
+    scopeKey?: string;
 }
 /**
  * Cache entry tracking when a preflight was last satisfied.

package/dist/guidance-cache.js

@@ -3,7 +3,7 @@
  * Serializes a CacheKey into a deterministic string for use as a Map key.
  */
 function serializeKey(key) {
-    return `${key.workspaceRoot}\0${key.branch}\0${key.posture}\0${key.riskClass}\0${key.fileBucket}`;
+    return `${key.workspaceRoot}\0${key.branch}\0${key.posture}\0${key.riskClass}\0${key.fileBucket}\0${key.scopeKey ?? ""}`;
 }
 /**
  * In-memory cache tracking satisfied preflight checks per unique context.