forge-workflow 0.1.0-beta.3 → 0.1.0-beta.5

package/lib/protected-state-authority.js

@@ -0,0 +1,305 @@
+'use strict';
+
+// The ignored JSONL audit log is visibility-only. Workflow write authority is
+// an append-only Kernel capability scoped to one worktree and consumed once.
+
+const { randomUUID } = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const { resolveOwnedKernel, closeIfOwned } = require('./kernel/owned-kernel');
+const { hashProtectedContent, normalizeRepoPath } = require('./protected-state-surfaces');
+
+const PROTECTED_STATE_ENTITY_TYPE = 'protected_state';
+const PROTECTED_STATE_AUTHORIZATION_ISSUED = 'protected_state.authorization.issued';
+const PROTECTED_STATE_AUTHORIZATION_CONSUMED = 'protected_state.authorization.consumed';
+const PROTECTED_STATE_AUTHORIZATION_VERSION = 1;
+const PROTECTED_STATE_AUTHORIZATION_ORIGIN = 'cli';
+const NPM_WORKFLOW_SOURCE_COMMAND = 'forge release generate-npm-workflow';
+
+function resolveWorktreeScope(projectRoot, deps = {}) {
+	const resolved = path.resolve(projectRoot);
+	const realpath = deps.realpathSync || fs.realpathSync.native;
+	let canonical;
+	try {
+		canonical = realpath(resolved);
+	} catch {
+		canonical = resolved;
+	}
+	if (process.platform === 'win32') canonical = canonical.toLowerCase();
+	return hashProtectedContent(canonical);
+}
+
+function authorizationEntityId(worktreeScope, filePath) {
+	return `${worktreeScope}:${normalizeRepoPath(filePath)}`;
+}
+
+function parsePayload(row) {
+	try {
+		return row?.payload_json ? JSON.parse(row.payload_json) : (row?.payload || {});
+	} catch {
+		return {};
+	}
+}
+
+function parseAuthorizationEvent(row) {
+	const payload = parsePayload(row);
+	return {
+		eventType: row?.event_type,
+		actor: row?.actor,
+		payloadActor: payload.actor,
+		origin: row?.origin,
+		entityId: row?.entity_id,
+		createdAt: row?.created_at,
+		version: payload.version,
+		capabilityId: payload.capabilityId,
+		path: normalizeRepoPath(payload.path),
+		surface: payload.surface,
+		contentHash: payload.contentHash,
+		operation: payload.operation,
+		sourceCommand: payload.sourceCommand,
+		worktreeScope: payload.worktreeScope,
+	};
+}
+
+function blockedDecision(request, reason) {
+	return {
+		allowed: false,
+		decision: 'blocked',
+		actor: request.actor,
+		path: normalizeRepoPath(request.path),
+		operation: request.operation || 'staged_edit',
+		requiredSurface: request.surface,
+		declaredSurface: request.surface,
+		contentHash: hashProtectedContent(request.content),
+		reason,
+		repairHint: 'Regenerate the protected file through its owning Forge command, then stage that exact output.',
+	};
+}
+
+function evaluateAuthorization(request, rows = []) {
+	const expected = {
+		actor: request.actor,
+		path: normalizeRepoPath(request.path),
+		surface: request.surface,
+		contentHash: hashProtectedContent(request.content),
+		worktreeScope: request.worktreeScope,
+	};
+	const issued = rows
+		.filter(row => row?.event_type === PROTECTED_STATE_AUTHORIZATION_ISSUED)
+		.map(parseAuthorizationEvent);
+	const consumedCapabilities = new Set(rows
+		.filter(row => row?.event_type === PROTECTED_STATE_AUTHORIZATION_CONSUMED)
+		.map(row => parseAuthorizationEvent(row).capabilityId)
+		.filter(Boolean));
+	const active = issued.filter(event => !consumedCapabilities.has(event.capabilityId));
+
+	if (issued.length === 0) {
+		return blockedDecision(request, 'No Forge-owned authorization exists for this protected path and content-bound write.');
+	}
+	if (active.length === 0) {
+		return blockedDecision(request, 'The latest Forge-owned authorization was already consumed; stale and same-content replays are denied.');
+	}
+	if (active.length !== 1) {
+		return blockedDecision(request, 'Protected-state authority is ambiguous because multiple unconsumed authorizations exist; failing closed.');
+	}
+	const latest = active[0];
+
+	const structurallyValid =
+		latest.version === PROTECTED_STATE_AUTHORIZATION_VERSION &&
+		typeof latest.capabilityId === 'string' && latest.capabilityId.length > 0 &&
+		latest.origin === PROTECTED_STATE_AUTHORIZATION_ORIGIN &&
+		latest.actor === latest.payloadActor &&
+		latest.worktreeScope === expected.worktreeScope &&
+		latest.entityId === authorizationEntityId(expected.worktreeScope, latest.path) &&
+		latest.sourceCommand === NPM_WORKFLOW_SOURCE_COMMAND;
+	if (!structurallyValid) {
+		return blockedDecision(request, 'The latest Forge-owned authorization is malformed or was not issued by the owning command.');
+	}
+
+	if (
+		latest.actor !== expected.actor ||
+		latest.path !== expected.path ||
+		latest.surface !== expected.surface ||
+		latest.contentHash !== expected.contentHash
+	) {
+		return blockedDecision(request, 'The latest Forge-owned content-bound authorization does not match this actor, surface, path, and content hash.');
+	}
+
+	return {
+		allowed: true,
+		decision: 'allowed',
+		actor: expected.actor,
+		path: expected.path,
+		operation: request.operation || 'staged_edit',
+		requiredSurface: expected.surface,
+		declaredSurface: expected.surface,
+		contentHash: expected.contentHash,
+		capabilityId: latest.capabilityId,
+		worktreeScope: latest.worktreeScope,
+		reason: 'Staged content matches the latest unconsumed Forge-owned authorization.',
+		repairHint: null,
+	};
+}
+
+async function issueProtectedStateAuthorization(projectRoot, request = {}, options = {}) {
+	const actor = request.actor;
+	const normalizedPath = normalizeRepoPath(request.path);
+	if (!actor || !request.surface || !normalizedPath || request.content === undefined) {
+		throw new TypeError('Protected state authorization requires actor, surface, path, and content');
+	}
+
+	const capabilityId = options.capabilityId || randomUUID();
+	const createdAt = options.now || new Date().toISOString();
+	const worktreeScope = options.worktreeScope || resolveWorktreeScope(projectRoot, options.deps);
+	const entityId = authorizationEntityId(worktreeScope, normalizedPath);
+	const event = {
+		entity_type: PROTECTED_STATE_ENTITY_TYPE,
+		entity_id: entityId,
+		event_type: PROTECTED_STATE_AUTHORIZATION_ISSUED,
+		idempotency_key: `${PROTECTED_STATE_AUTHORIZATION_ISSUED}:${capabilityId}`,
+		expected_revision: 0,
+		actor,
+		origin: PROTECTED_STATE_AUTHORIZATION_ORIGIN,
+		payload: {
+			version: PROTECTED_STATE_AUTHORIZATION_VERSION,
+			capabilityId,
+			actor,
+			path: normalizedPath,
+			surface: request.surface,
+			contentHash: hashProtectedContent(request.content),
+			worktreeScope,
+			operation: request.operation || 'generate',
+			sourceCommand: request.sourceCommand || NPM_WORKFLOW_SOURCE_COMMAND,
+		},
+		created_at: createdAt,
+	};
+
+	const kernel = await resolveOwnedKernel(projectRoot, options.deps);
+	try {
+		const existingRows = await kernel.driver.listKernelEvents(
+			PROTECTED_STATE_ENTITY_TYPE,
+			entityId,
+			{},
+			kernel.config,
+		);
+		const consumedCapabilities = new Set((existingRows || [])
+			.filter(row => row?.event_type === PROTECTED_STATE_AUTHORIZATION_CONSUMED)
+			.map(row => parseAuthorizationEvent(row).capabilityId)
+			.filter(Boolean));
+		const activeCapabilities = (existingRows || [])
+			.filter(row => row?.event_type === PROTECTED_STATE_AUTHORIZATION_ISSUED)
+			.map(parseAuthorizationEvent)
+			.filter(existing => existing.capabilityId && !consumedCapabilities.has(existing.capabilityId));
+		for (const existing of activeCapabilities) {
+			await kernel.driver.insertKernelEvent({
+				entity_type: PROTECTED_STATE_ENTITY_TYPE,
+				entity_id: entityId,
+				event_type: PROTECTED_STATE_AUTHORIZATION_CONSUMED,
+				idempotency_key: `${PROTECTED_STATE_AUTHORIZATION_CONSUMED}:${existing.capabilityId}`,
+				expected_revision: 0,
+				actor,
+				origin: PROTECTED_STATE_AUTHORIZATION_ORIGIN,
+				payload: {
+					version: PROTECTED_STATE_AUTHORIZATION_VERSION,
+					capabilityId: existing.capabilityId,
+					actor,
+					path: normalizedPath,
+					surface: existing.surface,
+					contentHash: existing.contentHash,
+					worktreeScope,
+					operation: 'superseded',
+					sourceCommand: request.sourceCommand || NPM_WORKFLOW_SOURCE_COMMAND,
+				},
+				created_at: createdAt,
+			}, {}, kernel.config);
+		}
+		const inserted = await kernel.driver.insertKernelEvent(event, {}, kernel.config);
+		return { success: true, capabilityId, event: parseAuthorizationEvent(inserted) };
+	} finally {
+		closeIfOwned(kernel);
+	}
+}
+
+async function issueNpmPublishWorkflowAuthorization(projectRoot, params = {}, options = {}) {
+	const {
+		NPM_PUBLISH_WORKFLOW_PATH,
+		renderNpmPublishWorkflow,
+	} = require('./npm-publish-workflow');
+	return issueProtectedStateAuthorization(projectRoot, {
+		actor: params.actor,
+		surface: 'workflows',
+		path: NPM_PUBLISH_WORKFLOW_PATH,
+		content: renderNpmPublishWorkflow(),
+		operation: 'generate_npm_workflow',
+		sourceCommand: NPM_WORKFLOW_SOURCE_COMMAND,
+	}, options);
+}
+
+async function authorizeAndConsumeProtectedStateWrites(projectRoot, requests = [], options = {}) {
+	if (requests.length === 0) return { success: true, decisions: [] };
+	const worktreeScope = options.worktreeScope || resolveWorktreeScope(projectRoot, options.deps);
+	const kernel = await resolveOwnedKernel(projectRoot, options.deps);
+	try {
+		const decisions = [];
+		for (const request of requests) {
+			const normalizedPath = normalizeRepoPath(request.path);
+			const entityId = authorizationEntityId(worktreeScope, normalizedPath);
+			const rows = await kernel.driver.listKernelEvents(
+				PROTECTED_STATE_ENTITY_TYPE,
+				entityId,
+				{},
+				kernel.config,
+			);
+			decisions.push(evaluateAuthorization({
+				...request,
+				path: normalizedPath,
+				worktreeScope,
+			}, rows || []));
+		}
+
+		if (decisions.some(decision => !decision.allowed)) {
+			return { success: false, decisions };
+		}
+
+		for (const decision of decisions) {
+			const createdAt = options.now || new Date().toISOString();
+			await kernel.driver.insertKernelEvent({
+				entity_type: PROTECTED_STATE_ENTITY_TYPE,
+				entity_id: authorizationEntityId(decision.worktreeScope, decision.path),
+				event_type: PROTECTED_STATE_AUTHORIZATION_CONSUMED,
+				idempotency_key: `${PROTECTED_STATE_AUTHORIZATION_CONSUMED}:${decision.capabilityId}`,
+				expected_revision: 0,
+				actor: decision.actor,
+				origin: PROTECTED_STATE_AUTHORIZATION_ORIGIN,
+				payload: {
+					version: PROTECTED_STATE_AUTHORIZATION_VERSION,
+					capabilityId: decision.capabilityId,
+					actor: decision.actor,
+					path: decision.path,
+					surface: decision.requiredSurface,
+					contentHash: decision.contentHash,
+					worktreeScope: decision.worktreeScope,
+					operation: 'staged_edit',
+					sourceCommand: 'scripts/protected-state-check.js',
+				},
+				created_at: createdAt,
+			}, {}, kernel.config);
+		}
+
+		return { success: true, decisions };
+	} finally {
+		closeIfOwned(kernel);
+	}
+}
+
+module.exports = {
+	PROTECTED_STATE_ENTITY_TYPE,
+	PROTECTED_STATE_AUTHORIZATION_ISSUED,
+	PROTECTED_STATE_AUTHORIZATION_CONSUMED,
+	resolveWorktreeScope,
+	authorizationEntityId,
+	parseAuthorizationEvent,
+	evaluateAuthorization,
+	issueNpmPublishWorkflowAuthorization,
+	authorizeAndConsumeProtectedStateWrites,
+};

package/lib/protected-state-surfaces.js

@@ -1,7 +1,17 @@
 const fs = require('node:fs');
 const path = require('node:path');
-const { execFileSync } = require('node:child_process');
+const crypto = require('node:crypto');
 const { redact } = require('./audit-evidence');
+const { appendCappedJsonlRecord } = require('./capped-jsonl-log');
+
+/**
+ * Protected-state decisions are logged locally rather than to the kernel event
+ * stream: kernel events are issue-scoped and async, and this runs inside a
+ * synchronous pre-commit hook that has no issue id and must not open the kernel
+ * SQLite handle. Capped so a repeated blocked commit cannot grow it unbounded.
+ */
+const PROTECTED_STATE_AUDIT_LOG = '.forge/protected-state-audit.jsonl';
+const PROTECTED_STATE_AUDIT_MAX_RECORDS = 500;
 
 function normalizeRepoPath(filePath) {
 	return String(filePath || '')
@@ -10,6 +20,30 @@ function normalizeRepoPath(filePath) {
 		.replace(/\/+/g, '/');
 }
 
+function hashProtectedContent(content) {
+	const bytes = Buffer.isBuffer(content) ? content : Buffer.from(String(content), 'utf8');
+	return `sha256:${crypto.createHash('sha256').update(bytes).digest('hex')}`;
+}
+
+function createProtectedStateAuditRecord({ actor, surface, path: filePath, content, operation = 'generate' }) {
+	if (!actor || !surface || !filePath || content === undefined) {
+		throw new TypeError('Protected state audit record requires actor, surface, path, and content');
+	}
+
+	return {
+		kind: 'protected_state_write',
+		actor,
+		path: normalizeRepoPath(filePath),
+		decision: 'allowed',
+		requiredSurface: surface,
+		declaredSurface: surface,
+		operation,
+		contentHash: hashProtectedContent(content),
+		reason: `Forge API generated content for protected surface: ${surface}.`,
+		repairHint: null,
+	};
+}
+
 function startsWithAny(filePath, prefixes) {
 	return prefixes.some(prefix => filePath === prefix || filePath.startsWith(`${prefix}/`));
 }
@@ -42,13 +76,13 @@ const PROTECTED_SURFACES = [
 				'.forge/agent-log.ndjson',
 				'.beads/interactions.jsonl',
 			].includes(filePath),
-		repairHint: 'append-only logs must be written by the Forge or Beads audit writer; do not rewrite existing log content.',
+		repairHint: 'append-only logs must be written by the Forge audit writer; do not rewrite existing log content.',
 	},
 	{
 		id: 'beads_state',
-		label: 'Beads state',
+		label: 'Legacy Beads state',
 		matches: filePath => startsWithAny(filePath, ['.beads']),
-		repairHint: 'Use bd or Forge issue commands such as bd update, bd close, forge ready, or forge close.',
+		repairHint: 'A legacy .beads directory is import-only state. Import it with `forge migrate --from beads`, then use Forge issue commands such as forge ready or forge close.',
 	},
 	{
 		id: 'forge_config',
@@ -164,8 +198,12 @@ function nearestExistingPath(candidate) {
 	return current;
 }
 
+function realpathNearestExistingPath(candidate) {
+	return fs.realpathSync(nearestExistingPath(candidate));
+}
+
 function assertNoAncestorSymlinkEscape(root, target) {
-	const realRoot = fs.realpathSync(root);
+	const realRoot = realpathNearestExistingPath(root);
 	const existing = nearestExistingPath(path.dirname(target));
 	const existingStat = lstatIfPresent(existing);
 	if (existing !== root && existingStat?.isSymbolicLink()) {
@@ -177,7 +215,7 @@ function assertNoAncestorSymlinkEscape(root, target) {
 		};
 	}
 
-	const realExisting = fs.realpathSync(existing);
+	const realExisting = realpathNearestExistingPath(existing);
 	if (!pathStaysInsideRoot(realRoot, realExisting)) {
 		return {
 			allowed: false,
@@ -191,8 +229,8 @@ function assertNoAncestorSymlinkEscape(root, target) {
 
 function assertNoSymlinkEscape(root, target) {
 	const parent = path.dirname(target);
-	const realRoot = fs.realpathSync(root);
-	const existingParent = fs.existsSync(parent) ? fs.realpathSync(parent) : parent;
+	const realRoot = realpathNearestExistingPath(root);
+	const existingParent = realpathNearestExistingPath(parent);
 	if (!pathStaysInsideRoot(realRoot, existingParent)) {
 		return {
 			allowed: false,
@@ -297,7 +335,7 @@ function writeProtectedFile(projectRoot, filePath, content, options = {}) {
 	}
 
 	fs.writeFileSync(resolved.target, content, options.encoding || 'utf8');
-	return { ...decision, fullPath: resolved.target };
+	return { ...decision, contentHash: hashProtectedContent(content), fullPath: resolved.target };
 }
 
 function buildProtectedStateAuditEvent(decision) {
@@ -313,12 +351,14 @@ function buildProtectedStateAuditEvent(decision) {
 		requiredSurface: decision.requiredSurface,
 		declaredSurface: decision.declaredSurface || null,
 		operation: decision.operation || 'write',
+		contentHash: decision.contentHash || null,
 		reason: decision.reason,
 		repairHint: decision.repairHint,
 		metadata: {
 			actor: decision.actor || 'unknown',
 			path: decision.path,
 			operation: decision.operation || 'write',
+			contentHash: decision.contentHash || null,
 			requiredSurface: decision.requiredSurface,
 			declaredSurface: decision.declaredSurface || null,
 			decision: decision.decision,
@@ -330,51 +370,31 @@ function buildProtectedStateAuditEvent(decision) {
 	return redact(event);
 }
 
+/**
+ * Best-effort: a failed audit write is reported to the caller, never thrown, so
+ * the protected-state decision itself still stands.
+ */
 function recordProtectedStateAuditEvent(decision, options = {}) {
 	const event = buildProtectedStateAuditEvent(decision);
-	const runCommand = options.runCommand || execFileSync;
-	try {
-		const args = [
-			'audit',
-			'record',
-			'--json',
-			'--kind',
-			'protected_state_write',
-			'--model',
-			'forge-protected-state',
-			'--prompt',
-			JSON.stringify({
-				actor: event.actor,
-				path: event.path,
-				operation: event.operation,
-			}),
-			'--response',
-			JSON.stringify({
-				decision: event.decision,
-				requiredSurface: event.requiredSurface,
-				repairHint: event.repairHint,
-			}),
-		];
-
-		if (event.metadata) {
-			args.push('--meta-json', JSON.stringify(event.metadata));
-		}
+	const logPath = path.resolve(options.cwd || process.cwd(), PROTECTED_STATE_AUDIT_LOG);
+	const appendRecord = options.appendRecord || appendCappedJsonlRecord;
 
-		const output = runCommand('bd', args, {
-			cwd: options.cwd || process.cwd(),
-			encoding: 'utf8',
-			stdio: ['ignore', 'pipe', 'pipe'],
-			timeout: options.timeoutMs || 5000,
-		});
-		return { success: true, event, output };
+	try {
+		const record = { ...event, recordedAt: options.now || new Date().toISOString() };
+		appendRecord(logPath, record, options.maxRecords || PROTECTED_STATE_AUDIT_MAX_RECORDS);
+		return { success: true, event, logPath };
 	} catch (error) {
-		return { success: false, event, error: error.message };
+		return { success: false, event, logPath, error: error.message };
 	}
 }
 
 module.exports = {
 	PROTECTED_SURFACES,
+	PROTECTED_STATE_AUDIT_LOG,
+	PROTECTED_STATE_AUDIT_MAX_RECORDS,
 	normalizeRepoPath,
+	hashProtectedContent,
+	createProtectedStateAuditRecord,
 	resolveRepoRelativePath,
 	lstatIfPresent,
 	assertNoAncestorSymlinkEscape,

package/lib/release-readiness.js

@@ -413,13 +413,27 @@ function readSyncManifestScanRoots(projectRoot) {
   }
 }
 
+// Scan roots reach here in whatever spelling their source used — a plugin manifest
+// directory entry, a sync-manifest file, an explicit scanRoots option — so they are
+// normalized once, at the single place they are resolved. walkFiles would join a trailing
+// separator away and scan the tree regardless, while isBdCensusPath would build `root//`
+// and match nothing under it; normalizing here is what keeps the census and the
+// pre-commit predicate from disagreeing about which files count.
+function normalizeScanRoot(root) {
+  if (typeof root !== 'string' || root.length === 0) {
+    return '';
+  }
+  return normalizeRepoPath(root).replace(/[/\\]+$/, '');
+}
+
 function getScanRoots(projectRoot, options = {}) {
   const roots = options.scanRoots || getDefaultScanRoots(projectRoot);
   return [
-    ...new Set([
-      ...roots,
-      ...readSyncManifestScanRoots(projectRoot),
-    ]),
+    ...new Set(
+      [...roots, ...readSyncManifestScanRoots(projectRoot)]
+        .map(normalizeScanRoot)
+        .filter(Boolean),
+    ),
   ];
 }
 
@@ -557,6 +571,38 @@ function auditBdCallSites(projectRoot, options = {}) {
   };
 }
 
+// Would a change to this repo-relative path shift the bd call-site census?
+//
+// The pre-commit auto-heal (scripts/sync-d20-audit.js) asks this before doing any work,
+// so it must answer exactly what auditBdCallSites would scan. It is therefore assembled
+// from that walk's own pieces — getScanRoots, shouldSkipRelativePath, isTextFile,
+// SKIP_DIR_NAMES — rather than a parallel list that could drift from the gate.
+function isBdCensusPath(projectRoot, filePath, options = {}) {
+  const relativePath = safeNormalizeRepoPath(projectRoot, filePath);
+  if (!relativePath || shouldSkipRelativePath(relativePath) || !isTextFile(relativePath, projectRoot)) {
+    return false;
+  }
+
+  // getScanRoots already returns normalized roots — re-normalizing here would be a second
+  // copy of that rule, free to drift from the one auditBdCallSites walks.
+  return getScanRoots(projectRoot, options)
+    .some(root => {
+      // walkFiles applies no directory skips to a root that is itself a file.
+      if (relativePath === root) {
+        return true;
+      }
+      if (!relativePath.startsWith(`${root}/`)) {
+        return false;
+      }
+      // Below a directory root it refuses to descend into skipped directories.
+      return !relativePath
+        .slice(root.length + 1)
+        .split('/')
+        .slice(0, -1)
+        .some(directory => SKIP_DIR_NAMES.has(directory));
+    });
+}
+
 function readRepoFile(projectRoot, relativePath) {
   const fullPath = absolutePath(projectRoot, relativePath);
   return fs.existsSync(fullPath) ? fs.readFileSync(fullPath, 'utf8') : '';
@@ -2096,6 +2142,7 @@ module.exports = {
   auditBdCallSites,
   buildReadinessReport,
   canonicalizeAuditArtifact,
+  isBdCensusPath,
   renderBdCallSiteAuditMarkdown,
   renderReadinessReport,
   writeAuditArtifact,

package/lib/rules-sync.js

@@ -48,6 +48,10 @@ const CURSOR_RULE_FILES = {
   security: 'security-scanning.mdc',
   documentation: 'documentation.mdc',
   'kernel-tracking': 'kernel-tracking.mdc',
+  // The using-forge dispatch pointer as an always-apply Cursor rule — Cursor's native
+  // always-on carrier for the skill auto-trigger bootstrap (parallels the Claude SessionStart
+  // hook and the committed AGENTS.md for Codex). Thin pointer; full policy stays in the skill.
+  'using-forge': 'using-forge.mdc',
 };
 
 const CANONICAL_RULE_NAMES = Object.keys(CURSOR_RULE_FILES);

package/lib/runtime-health.js

@@ -172,17 +172,6 @@ function invokesForgeHook(line) {
   });
 }
 
-function invokesBeadsHook(line, hookName) {
-  const tokens = commandTokens(line);
-  return tokens.some((token, index) => (
-    commandName(token) === 'bd'
-    && toText(tokens[index + 1]).toLowerCase() === 'hooks'
-    && toText(tokens[index + 2]).toLowerCase() === 'run'
-    && toText(tokens[index + 3]).toLowerCase() === hookName
-    && isExecutingTokenPosition(tokens, index)
-  ));
-}
-
 function createDiagnostic(code, subject, message, repair, severity = 'hard-stop') {
   return {
     code,
@@ -216,7 +205,7 @@ function isUsableWindowsShellCandidate(candidate, options = {}) {
 function checkHookInstallation(projectRoot, options = {}) {
   const exec = options._exec || defaultExecFileSync;
   const platform = options.platform || process.platform;
-  const expectedRelativeHooksPaths = ['.lefthook/hooks', '.beads/hooks'];
+  const expectedRelativeHooksPaths = ['.lefthook/hooks'];
   const requiredHooks = ['pre-commit', 'pre-push'];
 
   function resolveGitRoot() {
@@ -269,23 +258,10 @@ function checkHookInstallation(projectRoot, options = {}) {
       const content = fs.readFileSync(filePath, 'utf8');
       const runsLefthook = hasExecutableHookCommand(content, invokesLefthook);
       const runsForgeHook = hasExecutableHookCommand(content, invokesForgeHook);
-      const runsBeadsHook = hasExecutableHookCommand(content, (line) => invokesBeadsHook(line, hookName));
 
       if (runsLefthook) return { active: true, provider: 'lefthook' };
       if (runsForgeHook) return { active: true, provider: 'forge' };
 
-      if (runsBeadsHook) {
-        const chainedHookPath = path.join(gitRoot, '.beads', 'hooks', hookName);
-        if (path.resolve(chainedHookPath) !== normalizedFilePath && fs.existsSync(chainedHookPath)) {
-          const chained = classifyHookFile(chainedHookPath, hookName, visited);
-          if (chained.active) {
-            return { active: true, provider: `beads->${chained.provider}` };
-          }
-        }
-
-        return { active: false, provider: 'beads-unverified' };
-      }
-
       return { active: false, provider: 'unknown' };
     } catch {
       return { active: false, provider: 'missing' };
@@ -333,7 +309,7 @@ function checkHookInstallation(projectRoot, options = {}) {
         state: 'inactive',
         verification: 'core.hooksPath',
         hooksPath,
-        message: `Git core.hooksPath is set to "${hooksPath}", not ".lefthook/hooks" or ".beads/hooks".`
+        message: `Git core.hooksPath is set to "${hooksPath}", not ".lefthook/hooks".`
       };
     }
   } catch {
@@ -488,9 +464,11 @@ function normalizeProjectRoot(projectRoot) {
 // shared resolver (env > .forge/config.yaml > default 'kernel'). Never throws and
 // never warns from the health path.
 function resolveHealthIssueBackend(options, projectRoot) {
-  if (options.issueBackend === 'kernel' || options.issueBackend === 'beads') {
+  if (options.issueBackend === 'kernel') {
     return options.issueBackend;
   }
+  // Anything else — including the retired `beads` value — falls through to the
+  // shared resolver, which answers 'kernel' for every unrecognized selector.
   return resolveIssueBackend({
     deps: options.backendDeps || {},
     env: options.env || process.env,
@@ -540,25 +518,16 @@ function checkRuntimeHealth(projectRoot, options = {}) {
   }
 
   if (!bd.available) {
-    if (issueBackend === 'beads') {
-      // Beads is the active issue backend, so bd is a genuine hard prerequisite.
-      diagnostics.push(createDiagnostic(
-        'BD_MISSING',
-        'bd',
-        'bd is required for stage-entry workflow checks when the beads issue backend is selected.'
-      ));
-    } else {
-      // Kernel is the default issue backend and needs no bd binary, so a missing bd
-      // must NOT hard-stop stage entry (the "no Beads install required" contract).
-      // Surface it as a non-blocking advisory instead.
-      advisories.push(createDiagnostic(
-        'BD_MISSING',
-        'bd',
-        'bd is not installed. The kernel issue backend does not require it; install bd only if you switch to the beads backend.',
-        undefined,
-        'advisory'
-      ));
-    }
+    // The kernel is the only issue backend and needs no bd binary, so bd is never a
+    // prerequisite and a missing bd must NOT hard-stop stage entry (the "no Beads
+    // install required" contract). It stays a non-blocking advisory.
+    advisories.push(createDiagnostic(
+      'BD_MISSING',
+      'bd',
+      'bd is not installed. Forge does not require it — the kernel issue backend is the only backend.',
+      undefined,
+      'advisory'
+    ));
   }
 
   if (!gh.available) {