opencode-workflow-guard 1.16.0 → 1.17.0

package/src/workflow-guard.ts

@@ -22,7 +22,7 @@ import { expandShellTargetPath, isPathOutsideWorkspace, OPENCODE_SCRATCH_DIR, re
 import { beginReadObservation, clearReadFingerprints, recordMutationObservation, recordSuccessfulRead, staleWriteReason } from "./policies/stale-write.ts";
 import { ToolInvocationLifecycle } from "./lib/tool-lifecycle.ts";
 import { ToolOutcomeTracker, type ToolOutcomePart } from "./lib/tool-outcomes.ts";
-import { guardToolCallImpl, isReadOnlyRole, SHELL_TOOL_NAMES } from "./lib/guard-dispatcher.ts";
+import { guardToolCallImpl, isMutatingSurfaceTool, isReadOnlyRole, SHELL_TOOL_NAMES } from "./lib/guard-dispatcher.ts";
 import { createCustomTools, buildWorkflowGuardSystemGuidance } from "./lib/custom-tools.ts";
 import type { PolicyDecision, TodoSdkClient } from "./lib/types.ts";
 export { isReadOnlyRole } from "./lib/guard-dispatcher.ts";
@@ -76,6 +76,9 @@ import {
 	isReviewRequired,
 	isSubagentReviewRequired,
 	isDocumentationRequired,
+	isLiveDocsRequired,
+	getLiveDocFailureThreshold,
+	getResearchToolPatterns,
 	getSubagentMutationBudget,
 	isLearningEnabled,
 	isProjectMemoryEnabled,
@@ -114,6 +117,9 @@ export {
 	isReviewRequired,
 	isSubagentReviewRequired,
 	isDocumentationRequired,
+	isLiveDocsRequired,
+	getLiveDocFailureThreshold,
+	getResearchToolPatterns,
 	getSubagentMutationBudget,
 	isLearningEnabled,
 	getLearningInterventionBudget,
@@ -330,6 +336,20 @@ import { checkCompletionClaims } from "./policies/completion.ts";
 
 export { checkCompletionClaims };
 
+import { checkSweepingClaims } from "./policies/sweeping-claims.ts";
+
+export { checkSweepingClaims };
+
+import {
+	clearLiveDocsFloor,
+	isResearchTool,
+	liveDocsGatingReason,
+	recordLiveDocsFailure,
+	recordResearchLookup,
+} from "./policies/live-docs.ts";
+
+export { isResearchTool, liveDocsGatingReason };
+
 export { sendDesktopNotification } from "./policies/shell-safety.ts";
 export { checkInteractiveTtyCommand, checkPackageHygiene, escapeAppleScriptString };
 
@@ -341,6 +361,14 @@ function logObservation(client: unknown, message: string): void {
 	} catch {}
 }
 
+function logWarn(client: unknown, message: string): void {
+	try {
+		void (client as TodoSdkClient | undefined)?.app?.log?.({
+			body: { service: "workflow-guard", level: "warn", message },
+		});
+	} catch {}
+}
+
 /**
  * Public guard entry point. Audits every decision (block or allow) to a
  * durable JSONL file before returning.
@@ -490,6 +518,31 @@ export const WorkflowGuard: V1Plugin = async (ctx: Parameters<V1Plugin>[0]) => {
 						: "";
 					throw new Error(`[workflow-guard] ${reason}${circuitBreakerSuffix}`);
 				}
+				// Policy 25: after repeated failures with no live lookup since,
+				// block the guess-and-retry surfaces (mutations and shell) until
+				// the session grounds itself in current documentation. Research
+				// tools are never gated; an allowed research call records the
+				// lookup after it succeeds.
+				if (input.sessionID && isMutatingSurfaceTool(input.tool)) {
+					const threshold = getLiveDocFailureThreshold(toolWorktree);
+					if (isLiveDocsRequired(toolWorktree)) {
+						const researchReason = liveDocsGatingReason(input.sessionID, input.tool, threshold, getResearchToolPatterns(toolWorktree));
+						if (researchReason !== undefined) {
+							await emitBlockFeedback(researchReason);
+							logWarn(ctx.client, `[workflow-guard] ${researchReason}`);
+							audit({
+								ts: new Date().toISOString(),
+								sessionID: input.sessionID,
+								callID: input.callID,
+								tool: input.tool,
+								decision: "block",
+								phase: "decision",
+								reason: "live_docs_research_floor",
+							});
+							throw new Error(`[workflow-guard] ${researchReason}`);
+						}
+					}
+				}
 				toolLifecycle.start(input.sessionID, input.callID);
 				if (input.sessionID) {
 					const record = asRecord(args);
@@ -727,6 +780,20 @@ export const WorkflowGuard: V1Plugin = async (ctx: Parameters<V1Plugin>[0]) => {
 						input: { claim: check.claim, evidenceState: check.evidenceState },
 					});
 				}
+				// Policy 26: journal sweeping repository claims unsupported by
+				// read coverage. Observability only - never mutates output.text.
+				const sweeping = checkSweepingClaims(text, { sessionID });
+				if (sweeping.sweeping && sweeping.reason) {
+					logObservation(ctx.client, `[workflow-guard] sweeping claim mismatch: ${sweeping.reason}`);
+					audit({
+						ts: new Date().toISOString(),
+						sessionID,
+						tool: "experimental.text.complete",
+						decision: "allow",
+						reason: `Sweeping claim '${sweeping.claim}' with ${sweeping.readFileCount} file(s) read`,
+						input: { claim: sweeping.claim, readFileCount: sweeping.readFileCount },
+					});
+				}
 			} catch {}
 		},
 
@@ -793,6 +860,17 @@ export const WorkflowGuard: V1Plugin = async (ctx: Parameters<V1Plugin>[0]) => {
 			if (event?.type === "message.part.updated") {
 				const outcome = toolOutcomes.record((event.properties as { part?: ToolOutcomePart })?.part ?? {});
 				if (outcome) {
+					// Policy 25 research floor: a failed call accrues debt; a
+					// successful live-source lookup clears it. Unrelated
+					// successes intentionally do not clear it. A research
+					// attempt never accrues debt even when it fails: otherwise
+					// a flaky network would deepen the block the agent is
+					// already trying to escape, and the floor would deadlock.
+					if (isResearchTool(outcome.tool, getResearchToolPatterns(getSessionBoundWorkspace(outcome.sessionID) || effectiveRoot))) {
+						if (outcome.status !== "error") recordResearchLookup(outcome.sessionID);
+					} else if (outcome.status === "error") {
+						recordLiveDocsFailure(outcome.sessionID);
+					}
 					audit({
 						ts: new Date().toISOString(),
 						sessionID: outcome.sessionID,
@@ -865,6 +943,7 @@ export const WorkflowGuard: V1Plugin = async (ctx: Parameters<V1Plugin>[0]) => {
 					clearReadFingerprints(sessionID);
 					toolLifecycle.clearSession(sessionID);
 					toolLifecycle.takeRecoveryRun(sessionID);
+					clearLiveDocsFloor(sessionID);
 					await runWithRuntimeState(effectiveRoot, ctx.client, () => clearContinuationState(sessionID));
 				}
 			}

package/test/test.mts

@@ -78,6 +78,9 @@ import {
 	checkLockfileSync,
 	branchHasDocumentationChange,
 	isDocumentationRequired,
+	isLiveDocsRequired,
+	getLiveDocFailureThreshold,
+	getResearchToolPatterns,
 	loadedPluginVersion,
 	qualifiedHostVersion,
 	isReviewRequired,
@@ -127,6 +130,17 @@ import { scanSessionTodos, toolPartName, detectTodoCapability, recordedTodoCapab
 import { buildPolicyPosture, renderPolicyPosture } from "../src/lib/policy-posture.ts";
 import { pluginKeyFor, preparePluginUpdate } from "../src/lib/config-writer.mjs";
 import { effectiveTodosWithOwner, isReadOnlyTodo, readOnlyTodoCompletions, recordTodoTaskStarts, todoEvidenceReport, unverifiedTodoCompletions, validateTodoLifecycle } from "../src/policies/todo.ts";
+import {
+	LiveDocsResearchFloor,
+	clearLiveDocsFloor,
+	isResearchTool,
+	liveDocsFailureCount,
+	liveDocsGatingReason,
+	recordLiveDocsFailure,
+	recordResearchLookup,
+} from "../src/policies/live-docs.ts";
+import { MIN_SWEEPING_READ_COVERAGE, checkSweepingClaims } from "../src/policies/sweeping-claims.ts";
+import { beginReadObservation, clearReadFingerprints, recordSuccessfulRead, sessionReadFileCount } from "../src/policies/stale-write.ts";
 import { todoTaskStarts, clearTodoSessionState } from "../src/lib/state.ts";
 import { resetPluginInstancesForTesting } from "../src/lib/plugin-instance.ts";
 import { claimToolCall, releaseToolCallClaim, resetToolCallClaimsForTesting } from "../src/lib/call-claims.ts";
@@ -1791,6 +1805,201 @@ for (let i = 0; i <= 4096; i++) boundedTracker.recordFallbackCompleted("s-fallba
 check("fallback call deduplication evicts old calls from its bounded window", boundedTracker.recordFallbackCompleted("s-fallback-bounded", "fallback-0", "bash")?.status === "completed");
 check("invalid tool timing is omitted", new ToolOutcomeTracker().record({ type: "tool", sessionID: "s-timing", callID: "timing", tool: "bash", state: { status: "completed", time: { start: Number.NaN, end: Number.POSITIVE_INFINITY } } })?.durationMs === undefined);
 
+// ── Policy 25: live-documentation research floor ──
+console.log("- live-docs research floor -");
+check("recognises builtin research tools", isResearchTool("websearch") && isResearchTool("webfetch"));
+check("recognises MCP documentation tools", isResearchTool("context7_resolve-library-id") && isResearchTool("mcp__context7__get-library-docs"));
+check("recognises tokenised docs servers beyond context7", isResearchTool("mcp__deepwiki__read_wiki") && isResearchTool("mcp__tavily__search") && isResearchTool("mcp__brave__web_search"));
+check("tokenised matching does not read obvious non-docs tools as research", !isResearchTool("mcp__git__ref_list") && !isResearchTool("git_status"));
+// The policy exists to force a real lookup. A guard inspection tool or a
+// generic file reader must not clear the debt by name accident.
+check("guard inspection tools are not research", !isResearchTool("guard_review_followup_resolve") && !isResearchTool("guard_status") && !isResearchTool("guard_why"));
+check("generic readers and resolvers are not research", !isResearchTool("read_wiki_index") && !isResearchTool("resolve_conflict") && !isResearchTool("read_docs_page"));
+check("a bare docs-ish token is not enough on its own", !isResearchTool("docker") && !isResearchTool("doc") && !isResearchTool("wiki"));
+check("documented docs servers match through their namespace", isResearchTool("mcp__context7__get-library-docs") && isResearchTool("mcp__deepwiki__read_wiki") && isResearchTool("deepwiki_read_wiki"));
+check("operator-declared research patterns are honoured", isResearchTool("mcp__acme__lookup", ["acme"]) && !isResearchTool("mcp__acme__lookup"));
+check("does not treat unrelated tools as research", !isResearchTool("bash") && !isResearchTool("edit") && !isResearchTool("read"));
+
+const floorUnit = new LiveDocsResearchFloor();
+floorUnit.recordFailure("s-unit");
+floorUnit.recordFailure("s-unit");
+check("research floor accrues failures below threshold", floorUnit.gatingReason("s-unit", "edit", 3) === undefined);
+floorUnit.recordFailure("s-unit");
+check("research floor blocks a mutation at threshold with no lookup", typeof floorUnit.gatingReason("s-unit", "edit", 3) === "string");
+check(
+	"floor block names the operator escape when no research tool exists",
+	(floorUnit.gatingReason("s-unit", "edit", 3) ?? "").includes("requireLiveDocs: false"),
+);
+check("research floor never blocks a research tool", floorUnit.gatingReason("s-unit", "websearch", 3) === undefined);
+floorUnit.recordResearch("s-unit");
+check("successful lookup clears the floor", floorUnit.gatingReason("s-unit", "bash", 3) === undefined);
+check("floor disabled when threshold is non-positive", floorUnit.gatingReason("s-unit", "edit", 0) === undefined);
+
+// A failed (or cancelled) research attempt must not deepen the debt it was
+// meant to clear; otherwise a flaky lookup deadlocks the session.
+const floorDeadlock = new LiveDocsResearchFloor();
+for (const _ of [1, 2, 3]) floorDeadlock.recordFailure("s-deadlock");
+check("floor blocks before a research attempt", typeof floorDeadlock.gatingReason("s-deadlock", "bash", 3) === "string");
+check("a research tool stays ungated while the floor is active", floorDeadlock.gatingReason("s-deadlock", "mcp__deepwiki__read_wiki", 3) === undefined);
+check("an operator-declared research tool stays ungated too", floorDeadlock.gatingReason("s-deadlock", "mcp__acme__lookup", 3, ["acme"]) === undefined);
+floorDeadlock.recordResearch("s-deadlock");
+check("clearing the floor lets the mutation through", floorDeadlock.gatingReason("s-deadlock", "bash", 3) === undefined);
+
+// Module-level helpers share state; a fresh session isolates the check.
+recordLiveDocsFailure("s-live-helpers");
+recordLiveDocsFailure("s-live-helpers");
+recordLiveDocsFailure("s-live-helpers");
+check("module helper exposes failures-since-research", liveDocsFailureCount("s-live-helpers") === 3);
+check("module helper gates mutation above threshold", typeof liveDocsGatingReason("s-live-helpers", "apply_patch", 3) === "string");
+recordResearchLookup("s-live-helpers");
+check("module helper clears debt after a lookup", liveDocsFailureCount("s-live-helpers") === 0 && liveDocsGatingReason("s-live-helpers", "edit", 3) === undefined);
+clearLiveDocsFloor("s-live-helpers");
+
+const prevRequireLive = process.env.WORKFLOW_GUARD_REQUIRE_LIVE_DOCS;
+const prevThreshold = process.env.WORKFLOW_GUARD_LIVE_DOC_THRESHOLD;
+delete process.env.WORKFLOW_GUARD_REQUIRE_LIVE_DOCS;
+delete process.env.WORKFLOW_GUARD_LIVE_DOC_THRESHOLD;
+check("live-docs research floor is enabled by default", isLiveDocsRequired(root) === true);
+check("live-docs failure threshold defaults to 3", getLiveDocFailureThreshold(root) === 3);
+process.env.WORKFLOW_GUARD_REQUIRE_LIVE_DOCS = "0";
+check("env override can disable the research floor", isLiveDocsRequired(root) === false);
+delete process.env.WORKFLOW_GUARD_REQUIRE_LIVE_DOCS;
+process.env.WORKFLOW_GUARD_LIVE_DOC_THRESHOLD = "5";
+check("env override can raise the research threshold", getLiveDocFailureThreshold(root) === 5);
+process.env.WORKFLOW_GUARD_LIVE_DOC_THRESHOLD = "5abc";
+check("trailing junk in the threshold is rejected, not silently parsed", getLiveDocFailureThreshold(root) === 3);
+process.env.WORKFLOW_GUARD_LIVE_DOC_THRESHOLD = "0";
+check("a zero threshold falls back to the default instead of disabling the floor", getLiveDocFailureThreshold(root) === 3);
+process.env.WORKFLOW_GUARD_LIVE_DOC_THRESHOLD = " 4 ";
+check("a padded threshold value is still honoured", getLiveDocFailureThreshold(root) === 4);
+delete process.env.WORKFLOW_GUARD_LIVE_DOC_THRESHOLD;
+const prevResearchTools = process.env.WORKFLOW_GUARD_RESEARCH_TOOLS;
+process.env.WORKFLOW_GUARD_RESEARCH_TOOLS = "acme,corp-docs";
+check("operator research tool patterns come from the environment", getResearchToolPatterns(root).join(",") === "acme,corp-docs");
+delete process.env.WORKFLOW_GUARD_RESEARCH_TOOLS;
+if (prevResearchTools === undefined) delete process.env.WORKFLOW_GUARD_RESEARCH_TOOLS; else process.env.WORKFLOW_GUARD_RESEARCH_TOOLS = prevResearchTools;
+delete process.env.WORKFLOW_GUARD_LIVE_DOC_THRESHOLD;
+if (prevRequireLive === undefined) delete process.env.WORKFLOW_GUARD_REQUIRE_LIVE_DOCS; else process.env.WORKFLOW_GUARD_REQUIRE_LIVE_DOCS = prevRequireLive;
+if (prevThreshold === undefined) delete process.env.WORKFLOW_GUARD_LIVE_DOC_THRESHOLD; else process.env.WORKFLOW_GUARD_LIVE_DOC_THRESHOLD = prevThreshold;
+
+const liveDocsPlugin = await pluginFn({ directory: root, client: fakeClient as any, project: {} as any, worktree: root, experimental_workspace: {} as any, serverUrl: new URL("http://localhost:4096"), $: undefined as any });
+const liveDocsSession = "s-live-docs-int";
+const livePart = (callID: string, status: "error" | "completed", tool = "bash") => ({
+	type: "tool",
+	sessionID: liveDocsSession,
+	callID,
+	tool,
+	state: { status, error: status === "error" ? `boom-${callID}` : undefined, time: { start: 1, end: 2 } },
+} as const);
+for (const id of ["ld-e1", "ld-e2", "ld-e3"]) {
+	await liveDocsPlugin.event?.({ event: { type: "message.part.updated", properties: { part: livePart(id, "error") } } } as any);
+}
+check("three failures accrue research debt in the entrypoint", liveDocsFailureCount(liveDocsSession) === 3);
+let liveBlockMessage = "";
+try {
+	await liveDocsPlugin["tool.execute.before"]?.({ tool: "bash", sessionID: liveDocsSession, callID: "ld-block" } as any, { args: { command: "ls" } } as any);
+} catch (err) {
+	liveBlockMessage = (err as Error).message;
+}
+check("repeated failures with no lookup block a shell call", liveBlockMessage.includes("Blocked:") && liveBlockMessage.includes("websearch"));
+let researchThrow = "";
+try {
+	await liveDocsPlugin["tool.execute.before"]?.({ tool: "websearch", sessionID: liveDocsSession, callID: "ld-research" } as any, { args: { query: "node fs api" } } as any);
+} catch (err) {
+	researchThrow = (err as Error).message;
+}
+check("research tool is never blocked by the floor", researchThrow === "");
+await liveDocsPlugin.event?.({ event: { type: "message.part.updated", properties: { part: livePart("ld-research", "completed", "websearch") } } } as any);
+check("successful lookup clears research debt in the entrypoint", liveDocsFailureCount(liveDocsSession) === 0);
+let liveAllowThrow = "";
+try {
+	await liveDocsPlugin["tool.execute.before"]?.({ tool: "bash", sessionID: liveDocsSession, callID: "ld-after" } as any, { args: { command: "ls" } } as any);
+} catch (err) {
+	liveAllowThrow = (err as Error).message;
+}
+check("shell call proceeds after the lookup clears the floor", liveAllowThrow === "");
+
+// Unrelated success does not clear debt; idle preserves it; delete clears it.
+const liveDocsSession2 = "s-live-docs-int2";
+const livePart2 = (callID: string, status: "error" | "completed", tool = "bash") => ({
+	type: "tool",
+	sessionID: liveDocsSession2,
+	callID,
+	tool,
+	state: { status, error: status === "error" ? `boom-${callID}` : undefined, time: { start: 1, end: 2 } },
+} as const);
+for (const id of ["ld2-e1", "ld2-e2", "ld2-e3"]) {
+	await liveDocsPlugin.event?.({ event: { type: "message.part.updated", properties: { part: livePart2(id, "error") } } } as any);
+}
+await liveDocsPlugin.event?.({ event: { type: "message.part.updated", properties: { part: livePart2("ld2-ok", "completed", "bash") } } } as any);
+check("an unrelated successful tool does not clear research debt", liveDocsFailureCount(liveDocsSession2) === 3);
+let unrelatedBlock = "";
+try {
+	await liveDocsPlugin["tool.execute.before"]?.({ tool: "bash", sessionID: liveDocsSession2, callID: "ld2-block" } as any, { args: { command: "ls" } } as any);
+} catch (err) {
+	unrelatedBlock = (err as Error).message;
+}
+// The floor reason names websearch; the no-active-todo/edit gate would not, so
+// this asserts Policy 25 (not an unrelated gate) actually fired.
+check("mutation still blocks after an unrelated success", unrelatedBlock.includes("Blocked:") && unrelatedBlock.includes("websearch"));
+
+// A failed research attempt must not deepen the debt, and must clear on success.
+const liveDocsSession3 = "s-live-docs-int3";
+const livePart3 = (callID: string, status: "error" | "completed", tool = "bash") => ({
+	type: "tool",
+	sessionID: liveDocsSession3,
+	callID,
+	tool,
+	state: { status, error: status === "error" ? `boom-${callID}` : undefined, time: { start: 1, end: 2 } },
+} as const);
+for (const id of ["ld3-e1", "ld3-e2", "ld3-e3"]) {
+	await liveDocsPlugin.event?.({ event: { type: "message.part.updated", properties: { part: livePart3(id, "error") } } } as any);
+}
+check("floor is active before the research attempt", liveDocsFailureCount(liveDocsSession3) === 3);
+await liveDocsPlugin.event?.({ event: { type: "message.part.updated", properties: { part: livePart3("ld3-research-fail", "error", "websearch") } } } as any);
+check("a failed research attempt does not accrue research debt", liveDocsFailureCount(liveDocsSession3) === 3);
+await liveDocsPlugin.event?.({ event: { type: "message.part.updated", properties: { part: livePart3("ld3-research-ok", "completed", "websearch") } } } as any);
+check("a successful research attempt clears the debt", liveDocsFailureCount(liveDocsSession3) === 0);
+let worktreeThrow = "";
+try {
+	await liveDocsPlugin["tool.execute.before"]?.({ tool: "guard_worktree_create", sessionID: liveDocsSession3, callID: "ld3-wt" } as any, { args: { branch: "feat/x" } } as any);
+} catch (err) {
+	worktreeThrow = (err as Error).message;
+}
+check("a mutating lifecycle tool is not blocked once the floor is clear", !worktreeThrow.includes("websearch"));
+clearLiveDocsFloor(liveDocsSession3);
+
+// Positive direction: a lifecycle tool must be blocked while the floor is
+// active, or the guard's own tools are the way past its gate.
+const liveDocsSession4 = "s-live-docs-int4";
+for (const _ of [1, 2, 3]) recordLiveDocsFailure(liveDocsSession4);
+let worktreeBlocked = "";
+try {
+	await liveDocsPlugin["tool.execute.before"]?.({ tool: "guard_worktree_create", sessionID: liveDocsSession4, callID: "ld4-wt" } as any, { args: { branch: "feat/y" } } as any);
+} catch (err) {
+	worktreeBlocked = (err as Error).message;
+}
+check("a mutating lifecycle tool is blocked while the floor is active", worktreeBlocked.includes("Blocked:") && worktreeBlocked.includes("websearch"));
+let restoreBlocked = "";
+try {
+	await liveDocsPlugin["tool.execute.before"]?.({ tool: "guard_recovery_restore", sessionID: liveDocsSession4, callID: "ld4-restore" } as any, { args: {} } as any);
+} catch (err) {
+	restoreBlocked = (err as Error).message;
+}
+check("recovery restore is blocked while the floor is active", restoreBlocked.includes("Blocked:") && restoreBlocked.includes("websearch"));
+clearLiveDocsFloor(liveDocsSession4);
+
+await liveDocsPlugin.event?.({ event: { type: "session.idle", properties: { sessionID: liveDocsSession2 } } } as any);
+check("session idle does not clear research debt", liveDocsFailureCount(liveDocsSession2) === 3);
+await liveDocsPlugin.event?.({ event: { type: "session.deleted", properties: { info: { id: liveDocsSession2 } } } } as any);
+check("session deletion clears research debt", liveDocsFailureCount(liveDocsSession2) === 0);
+
+// Regex narrowing: bare file-set phrases and benign wording stay unmatched.
+check("bare file-set phrasing is not a sweeping claim", !checkSweepingClaims("all files under src compile.").sweeping && !checkSweepingClaims("check the whole file.").sweeping);
+check("repo-level phrasing still matches", checkSweepingClaims("the entire repository follows this convention.").sweeping && checkSweepingClaims("all packages depend on it.").sweeping);
+clearLiveDocsFloor(liveDocsSession);
+clearLiveDocsFloor("s-live-docs-int2");
+
 // TUI companion plugin registers prompt status indicator slots
 let registeredSlots: Record<string, Function> = {};
 let registeredOrder: number | undefined;
@@ -4457,6 +4666,22 @@ check(
 	appLogs.some((entry) => entry?.body?.level === "warn" && String(entry?.body?.message).includes("blocked write")),
 );
 
+// Policy 25 blocks must reach the durable app log at warn level too.
+appLogs.length = 0;
+const liveDocLogSession = "s-live-doc-log";
+for (const _ of [1, 2, 3]) recordLiveDocsFailure(liveDocLogSession);
+try {
+	await loggingPlugin["tool.execute.before"]?.(
+		{ tool: "bash", sessionID: liveDocLogSession, callID: "ld-log" } as any,
+		{ args: { command: "ls" } } as any,
+	);
+} catch {}
+check(
+	"research floor block writes warning to app log",
+	appLogs.some((entry) => entry?.body?.level === "warn" && String(entry?.body?.message).includes("no live documentation lookup")),
+);
+clearLiveDocsFloor(liveDocLogSession);
+
 // Concurrent plugin instances keep SDK client state isolated (AsyncLocalStorage).
 const activeClient = {
 	session: {
@@ -4819,6 +5044,56 @@ const claimLogAudit = getRecentAuditEntries(50).find((e) => e.tool === "experime
 check("claims-vs-evidence mismatch is an info observation, not a block warning", appLogs.some((entry) => entry?.body?.level === "info" && String(entry?.body?.message).includes("completion claim mismatch")) && !appLogs.some((entry) => entry?.body?.level === "warn"));
 check("claims-vs-evidence observation remains an allowed audit event", claimLogAudit?.decision === "allow");
 
+// ── Policy 26: sweeping repo claims vs read coverage (observability) ──
+console.log("- sweeping-claims grounding (observability) -");
+check("benign text does not trigger a sweeping claim", !checkSweepingClaims("I refactored the module.").sweeping);
+check("whole-codebase phrasing is detected", checkSweepingClaims("The entire codebase uses this pattern.").sweeping);
+check("no-other-callers phrasing is detected", checkSweepingClaims("No other callers reference this function.").sweeping);
+check("bare nothing-depends phrasing is detected without 'else'", checkSweepingClaims("Nothing depends on it.").sweeping && checkSweepingClaims("Nothing else depends on it.").sweeping);
+check(
+	"a sweeping claim with thin read coverage is flagged",
+	typeof checkSweepingClaims("Nothing else uses this helper.", { sessionID: "s-sweep-thin" }).reason === "string",
+);
+const sweepCoverageDir = mkdtempSync(join(tmpdir(), "wg-sweep-coverage-"));
+for (let i = 0; i < MIN_SWEEPING_READ_COVERAGE; i++) {
+	const p = join(sweepCoverageDir, `f${i}.txt`);
+	writeFileSync(p, `content ${i}`);
+	const obs = beginReadObservation(p);
+	if (obs) recordSuccessfulRead(obs, "s-sweep-backed");
+}
+check("read coverage counts distinct files", sessionReadFileCount("s-sweep-backed") === MIN_SWEEPING_READ_COVERAGE);
+const backed = checkSweepingClaims("The whole repository follows this convention.", { sessionID: "s-sweep-backed" });
+check("a sweeping claim backed by read coverage is not flagged", backed.sweeping && backed.reason === undefined);
+clearReadFingerprints("s-sweep-backed");
+clearReadFingerprints("s-sweep-thin");
+rmSync(sweepCoverageDir, { recursive: true, force: true });
+
+// Hook integration: sweeping mismatch is journaled, not blocked.
+const sweepAuditBefore = getRecentAuditEntries(50).filter((e) => e.tool === "experimental.text.complete" && String(e.reason).includes("Sweeping claim")).length;
+appLogs.length = 0;
+await loggingPlugin["experimental.text.complete"]?.(
+	{ sessionID: "s-sweep-hook", messageID: "m3", partID: "p3" } as any,
+	{ text: "The entire codebase relies on this invariant." } as any,
+);
+const sweepAuditAfter = getRecentAuditEntries(50).filter((e) => e.tool === "experimental.text.complete" && String(e.reason).includes("Sweeping claim")).length;
+check("sweeping-claim mismatch is journaled via the hook", sweepAuditAfter > sweepAuditBefore);
+check(
+	"sweeping-claim mismatch is an info observation, not a block warning",
+	appLogs.some((entry) => entry?.body?.level === "info" && String(entry?.body?.message).includes("sweeping claim mismatch")) &&
+		!appLogs.some((entry) => entry?.body?.level === "warn"),
+);
+// Negative hook case: a non-sweeping message must not journal a sweeping entry,
+// so the positive assertion above cannot pass on Policy 24's row alone.
+const sweepCleanBefore = getRecentAuditEntries(50).filter((e) => String(e.reason).includes("Sweeping claim")).length;
+await loggingPlugin["experimental.text.complete"]?.(
+	{ sessionID: "s-sweep-clean", messageID: "m4", partID: "p4" } as any,
+	{ text: "I refactored the helper and added a test." } as any,
+);
+const sweepCleanAfter = getRecentAuditEntries(50).filter((e) => String(e.reason).includes("Sweeping claim")).length;
+check("a non-sweeping message journals no sweeping-claim entry", sweepCleanAfter === sweepCleanBefore);
+clearReadFingerprints("s-sweep-hook");
+clearReadFingerprints("s-sweep-clean");
+
 // tool.definition enriches todowrite's description with the gate note
 const defPlugin = await WorkflowGuard({ directory: root, worktree: root, client: fakeClient as any } as any);
 const todoDef = { description: "Write the todo list.", parameters: {} };
@@ -5399,6 +5674,33 @@ releaseToolCallClaim("module-a", "s-v2-claim", "call-claim", "read");
 check("a settled call can be claimed by the next copy", claimToolCall("module-b", "s-v2-claim", "call-claim", "read") === true);
 check("claims without a call id are never shared across instances", claimToolCall("module-a", "s-v2-claim", undefined, "read") === true && claimToolCall("module-b", "s-v2-claim", undefined, "read") === true);
 resetToolCallClaimsForTesting();
+// A floor block must release the claim it acquired before the throw, or the
+// next copy of this call can never run and the block leaks into a timeout.
+resetToolCallClaimsForTesting();
+const v2FloorSession = "s-v2-floor-claim";
+recordLiveDocsFailure(v2FloorSession);
+recordLiveDocsFailure(v2FloorSession);
+recordLiveDocsFailure(v2FloorSession);
+let v2FloorThrow = "";
+try {
+	await v2Owner.state.beforeHooks[0]?.({
+		tool: "write",
+		sessionID: v2FloorSession,
+		agent: "build",
+		messageID: "msg-v2-floor",
+		id: "call-v2-floor",
+		input: { filePath: join(v2DuplicateRoot, "floor.txt"), content: "x" },
+	});
+} catch (err) {
+	v2FloorThrow = (err as Error).message;
+}
+check("V2 floor block aborts the call", v2FloorThrow.includes("no live documentation lookup"));
+check(
+	"a V2 floor block releases its tool-call claim",
+	claimToolCall("module-after-floor", v2FloorSession, "call-v2-floor", "write") === true,
+);
+releaseToolCallClaim("module-after-floor", v2FloorSession, "call-v2-floor", "write");
+clearLiveDocsFloor(v2FloorSession);
 if (prevDuplicateDataHome === undefined) delete process.env.XDG_DATA_HOME;
 else process.env.XDG_DATA_HOME = prevDuplicateDataHome;
 rmSync(v2DuplicateRoot, { recursive: true, force: true });