forge-workflow 0.1.0-beta.7 → 0.1.0-beta.8

package/lib/protected-state-authority.js

@@ -11,6 +11,7 @@ const { hashProtectedContent, normalizeRepoPath } = require('./protected-state-s
 const {
 	BUN_WORKFLOW_SPECS,
 	deriveBunWorkflowUpdate,
+	readCompleteBunPinBatch,
 	readIndexedPackageManifest,
 	readIndexedWorkflow,
 	readPinnedBunVersion,
@@ -28,6 +29,7 @@ const PROTECTED_STATE_AUTHORIZATION_CONSUMED = 'protected_state.authorization.co
 const PROTECTED_STATE_AUTHORIZATION_VERSION = 1;
 const PROTECTED_STATE_AUTHORIZATION_ORIGIN = 'cli';
 const NPM_WORKFLOW_SOURCE_COMMAND = 'forge release generate-npm-workflow';
+const TEST_WORKFLOW_SOURCE_COMMAND = 'forge release generate-test-workflow';
 const BUN_WORKFLOW_SOURCE_COMMAND = 'forge release update-bun-pins';
 const BUN_WORKFLOW_PATHS = new Set(BUN_WORKFLOW_SPECS.map(spec => spec.path));
 const SKILL_MIRROR_SOURCE_COMMAND = 'scripts/sync-agent-skills.js';
@@ -52,6 +54,13 @@ function owningWriter(pathname, surface) {
 			completionOperation: 'generate_npm_workflow_completed',
 		};
 	}
+	if (surface === 'workflows' && pathname === '.github/workflows/test.yml') {
+		return {
+			sourceCommand: TEST_WORKFLOW_SOURCE_COMMAND,
+			issueOperation: 'generate_test_workflow',
+			completionOperation: 'generate_test_workflow_completed',
+		};
+	}
 	if (surface === 'generated_harness' && /^\.agents\/skills\/[^/]+\/.+/.test(pathname)) {
 		return {
 			sourceCommand: SKILL_MIRROR_SOURCE_COMMAND,
@@ -165,7 +174,8 @@ function evaluateAuthorization(request, rows = []) {
 	const latest = active[0];
 	const writer = owningWriter(latest.path, latest.surface);
 
-	const bunPinWriter = [BUN_WORKFLOW_SOURCE_COMMAND, NPM_WORKFLOW_SOURCE_COMMAND].includes(writer?.sourceCommand);
+	const bunPinWriter = [BUN_WORKFLOW_SOURCE_COMMAND, NPM_WORKFLOW_SOURCE_COMMAND, TEST_WORKFLOW_SOURCE_COMMAND]
+		.includes(writer?.sourceCommand);
 	const structurallyValid =
 		writer !== null &&
 		latest.version === PROTECTED_STATE_AUTHORIZATION_VERSION &&
@@ -444,6 +454,57 @@ async function issueBunWorkflowAuthorization(projectRoot, params = {}, options =
 	}, options);
 }
 
+function resolveCurrentTestWorkflowTarget(projectRoot, params, requireWritten = false) {
+	let update;
+	try {
+		update = require('./test-workflow').resolveTestWorkflowUpdate(projectRoot, params.sourceHead);
+		if (update.version !== params.targetBunVersion) {
+			return { success: false, error: 'Protected test workflow target does not match the staged package.json Bun pin.' };
+		}
+		if (requireWritten) {
+			const fullPath = path.join(projectRoot, update.path);
+			const stat = fs.lstatSync(fullPath);
+			if (!stat.isFile() || stat.isSymbolicLink() || !fs.readFileSync(fullPath).equals(update.content)) {
+				return { success: false, error: 'Protected test workflow completion requires the exact generated workflow bytes.' };
+			}
+		}
+	} catch (error) {
+		return { success: false, error: error.message };
+	}
+	return { success: true, update };
+}
+
+/**
+ * Authorizes the canonical test workflow derived from the current staged package and template.
+ * The target and exact generated bytes are resolved again before the capability is inserted.
+ */
+async function issueTestWorkflowAuthorization(projectRoot, params = {}, options = {}) {
+	if (!isValidGitObjectId(params.sourceHead)) {
+		return { success: false, error: 'Protected test workflow authorization requires a full 40- or 64-character lowercase source HEAD.' };
+	}
+	const target = resolveCurrentTestWorkflowTarget(projectRoot, params);
+	if (!target.success) return target;
+	const expectedHash = hashProtectedContent(target.update.content);
+	return issueProtectedStateAuthorization(projectRoot, {
+		actor: params.actor,
+		surface: 'workflows',
+		path: target.update.path,
+		content: target.update.content,
+		operation: 'generate_test_workflow',
+		viaForgeApi: true,
+		sourceCommand: TEST_WORKFLOW_SOURCE_COMMAND,
+		sourceHead: params.sourceHead,
+		targetBunVersion: params.targetBunVersion,
+		verifyBeforeInsert: () => {
+			const fresh = resolveCurrentTestWorkflowTarget(projectRoot, params);
+			if (!fresh.success) return fresh;
+			return hashProtectedContent(fresh.update.content) === expectedHash
+				? { success: true }
+				: { success: false, error: 'Protected test workflow target changed during authorization.' };
+		},
+	}, options);
+}
+
 function findExactAuthorization(rows, params, expected) {
 	const issued = (rows || [])
 		.filter(row => row?.event_type === PROTECTED_STATE_AUTHORIZATION_ISSUED)
@@ -645,6 +706,74 @@ async function completeBunWorkflowAuthorization(projectRoot, params = {}, option
 	}
 }
 
+/**
+ * Completes only an active capability that matches the canonical target and exact written bytes.
+ * The staged target and generated file are rechecked before the completion event is inserted.
+ */
+async function completeTestWorkflowAuthorization(projectRoot, params = {}, options = {}) {
+	if (!isValidGitObjectId(params.sourceHead) || !params.capabilityId) {
+		return { success: false, error: 'Protected test workflow completion requires a capability id and full 40- or 64-character source HEAD.' };
+	}
+	const target = resolveCurrentTestWorkflowTarget(projectRoot, params, true);
+	if (!target.success) return target;
+	const actor = params.actor;
+	const normalizedPath = normalizeRepoPath(target.update.path);
+	const contentHash = hashProtectedContent(target.update.content);
+	const worktreeScope = options.worktreeScope || resolveWorktreeScope(projectRoot, options.deps);
+	const entityId = authorizationEntityId(worktreeScope, normalizedPath);
+	const kernel = await resolveOwnedKernel(projectRoot, options.deps);
+	try {
+		const rows = await kernel.driver.listKernelEvents(PROTECTED_STATE_ENTITY_TYPE, entityId, {}, kernel.config);
+		const { exactIssued, consumed } = findExactAuthorization(rows, params, {
+			actor,
+			entityId,
+			path: normalizedPath,
+			surface: 'workflows',
+			contentHash,
+			worktreeScope,
+			operation: 'generate_test_workflow',
+			writeIntent: 'update',
+			sourceCommand: TEST_WORKFLOW_SOURCE_COMMAND,
+			targetBunVersion: params.targetBunVersion,
+		});
+		if (!exactIssued || consumed) {
+			return { success: false, error: 'Protected test workflow completion does not match one active exact authorization.' };
+		}
+		const fresh = resolveCurrentTestWorkflowTarget(projectRoot, params, true);
+		if (!fresh.success || hashProtectedContent(fresh.update.content) !== contentHash) {
+			return fresh.success ? { success: false, error: 'Protected test workflow target changed during completion.' } : fresh;
+		}
+		const inserted = await kernel.driver.insertKernelEvent({
+			entity_type: PROTECTED_STATE_ENTITY_TYPE,
+			entity_id: entityId,
+			event_type: PROTECTED_STATE_WRITE_COMPLETED,
+			idempotency_key: `${PROTECTED_STATE_WRITE_COMPLETED}:${params.capabilityId}`,
+			expected_revision: 0,
+			actor,
+			origin: PROTECTED_STATE_AUTHORIZATION_ORIGIN,
+			payload: {
+				version: PROTECTED_STATE_AUTHORIZATION_VERSION,
+				capabilityId: params.capabilityId,
+				actor,
+				path: normalizedPath,
+				surface: 'workflows',
+				contentHash,
+				sourceHead: params.sourceHead,
+				worktreeScope,
+				writeIntent: 'update',
+				operation: 'generate_test_workflow_completed',
+				viaForgeApi: true,
+				sourceCommand: TEST_WORKFLOW_SOURCE_COMMAND,
+				targetBunVersion: params.targetBunVersion,
+			},
+			created_at: options.now || new Date().toISOString(),
+		}, {}, kernel.config);
+		return { success: true, capabilityId: params.capabilityId, event: parseAuthorizationEvent(inserted) };
+	} finally {
+		closeIfOwned(kernel);
+	}
+}
+
 async function cancelBunWorkflowBatchAuthorizations(projectRoot, requests = [], options = {}) {
 	if (requests.length === 0) return { success: true, results: [] };
 	const worktreeScope = options.worktreeScope || resolveWorktreeScope(projectRoot, options.deps);
@@ -655,7 +784,7 @@ async function cancelBunWorkflowBatchAuthorizations(projectRoot, requests = [],
 			const normalizedPath = normalizeRepoPath(request.path);
 			const writer = owningWriter(normalizedPath, 'workflows');
 			if (!request.actor || !isValidGitObjectId(request.sourceHead) || !request.capabilityId ||
-				!writer || ![BUN_WORKFLOW_SOURCE_COMMAND, NPM_WORKFLOW_SOURCE_COMMAND].includes(writer.sourceCommand)) {
+				!writer || ![BUN_WORKFLOW_SOURCE_COMMAND, NPM_WORKFLOW_SOURCE_COMMAND, TEST_WORKFLOW_SOURCE_COMMAND].includes(writer.sourceCommand)) {
 				results.push({ success: false, path: normalizedPath, capabilityId: request.capabilityId, error: 'Invalid Bun workflow batch cancellation request.' });
 				continue;
 			}
@@ -707,7 +836,7 @@ async function cancelBunWorkflowBatchAuthorizations(projectRoot, requests = [],
 						writeIntent: 'update',
 						operation: 'batch_rollback',
 						viaForgeApi: true,
-						sourceCommand: BUN_WORKFLOW_SOURCE_COMMAND,
+						sourceCommand: writer.sourceCommand,
 					},
 					created_at: options.now || new Date().toISOString(),
 				}, {}, kernel.config);
@@ -954,41 +1083,111 @@ function validateBunDecisionTargets(projectRoot, decisions) {
 	}
 }
 
+/**
+ * Validates the complete staged Bun workflow projection, including canonical test workflow output
+ * when the pin is unchanged. Repositories with neither source nor staged template retain the legacy
+ * path; bootstrap must add the template and output together, and established deletion is incomplete.
+ */
 function validateCompleteBunPinBatch(projectRoot, options = {}) {
 	if (options.sourceHead === null) return { success: true };
 	let sourceHead;
 	let sourcePackage;
+	let snapshot;
 	try {
-		sourceHead = options.sourceHead || resolveCurrentHead(projectRoot);
-		sourcePackage = Buffer.from((options.readSourcePackageManifest || readSourcePackageManifest)(projectRoot, sourceHead));
+		sourceHead = options.sourceHead || resolveCurrentHead(projectRoot, options.execGit);
+		sourcePackage = Buffer.from(
+			(options.readSourcePackageManifest || readSourcePackageManifest)(projectRoot, sourceHead),
+		);
+		if (JSON.parse(sourcePackage.toString('utf8')).name !== 'forge-workflow') return { success: true };
 	} catch (error) {
 		if (error.message.includes('package.json is not a regular file at')) return { success: true };
 		return { success: false, error: `Could not verify the complete staged Bun pin update: ${error.message}` };
 	}
 	try {
-		if (JSON.parse(sourcePackage.toString('utf8')).name !== 'forge-workflow') return { success: true };
 		const sourceVersion = readPinnedBunVersion(sourcePackage);
-		const indexedPackage = Buffer.from((options.readIndexedPackageManifest || readIndexedPackageManifest)(projectRoot));
+		const indexedPackage = Buffer.from(
+			(options.readIndexedPackageManifest || readIndexedPackageManifest)(projectRoot),
+		);
 		const targetVersion = readPinnedBunVersion(indexedPackage);
-		if (targetVersion === sourceVersion) return { success: true };
-		if (resolveBunVersionTarget(projectRoot, options).version !== targetVersion) {
+		const testWorkflow = require('./test-workflow');
+		if (targetVersion === sourceVersion) {
+			const projection = (options.readTestWorkflowProjection || testWorkflow.readTestWorkflowProjection)(
+				projectRoot,
+				sourceHead,
+				options.execGit,
+			);
+			if (!Buffer.from(projection.sourcePackage).equals(sourcePackage)
+				|| !Buffer.from(projection.indexedPackage).equals(indexedPackage)) {
+				throw new Error('package.json changed while reading the staged test workflow projection');
+			}
+			if (projection.sourceTemplate === null && projection.indexedTemplate === null) return { success: true };
+			if (projection.indexedTemplate === null) {
+				return { success: false, error: `${testWorkflow.TEST_WORKFLOW_TEMPLATE_PATH} is not one regular file in the Git index.` };
+			}
+			if (projection.indexedWorkflow === null) {
+				return { success: false, error: `${testWorkflow.TEST_WORKFLOW_PATH} is not one regular file in the Git index.` };
+			}
+			const expectedTest = testWorkflow.renderTestWorkflow(projection.indexedTemplate, targetVersion);
+			if (!Buffer.from(projection.indexedWorkflow).equals(expectedTest)) {
+				return { success: false, error: `${testWorkflow.TEST_WORKFLOW_PATH} does not match the staged canonical template for Bun ${targetVersion}.` };
+			}
+			return { success: true };
+		}
+		const npmWorkflow = require('./npm-publish-workflow');
+		const hasLegacyReaders = options.readSourcePackageManifest || options.readIndexedPackageManifest
+			|| options.readSourceWorkflow || options.readIndexedWorkflow || options.readIndexedNpmPublishWorkflow;
+		if (options.readCompleteBunPinBatch || !hasLegacyReaders) {
+			snapshot = (options.readCompleteBunPinBatch || readCompleteBunPinBatch)(
+				projectRoot,
+				sourceHead,
+				[npmWorkflow.NPM_PUBLISH_WORKFLOW_PATH, testWorkflow.TEST_WORKFLOW_PATH],
+				options.execGit,
+			);
+			if (!Buffer.from(snapshot.source.get('package.json')).equals(sourcePackage)
+				|| !Buffer.from(snapshot.indexed.get('package.json')).equals(indexedPackage)) {
+				throw new Error('package.json changed while reading the complete Bun pin snapshot');
+			}
+		}
+		if (resolveBunVersionTarget(projectRoot, {
+			...options,
+			readIndexedPackageManifest: () => indexedPackage,
+		}).version !== targetVersion) {
 			return { success: false, error: 'The working package.json Bun pin differs from the staged pin.' };
 		}
 
 		for (const spec of BUN_WORKFLOW_SPECS) {
-			const baseline = (options.readSourceWorkflow || readSourceWorkflow)(projectRoot, sourceHead, spec.path);
+			const baseline = snapshot
+				? snapshot.source.get(spec.path)
+				: (options.readSourceWorkflow || readSourceWorkflow)(projectRoot, sourceHead, spec.path);
 			const expected = Buffer.from(renderBunWorkflowPin(spec.path, baseline, targetVersion));
-			const indexed = Buffer.from((options.readIndexedWorkflow || readIndexedWorkflow)(projectRoot, spec.path));
+			const indexed = Buffer.from(snapshot
+				? snapshot.indexed.get(spec.path)
+				: (options.readIndexedWorkflow || readIndexedWorkflow)(projectRoot, spec.path));
 			if (!indexed.equals(expected)) {
 				return { success: false, error: `A staged Bun pin change requires the complete generated workflow set; ${spec.path} does not match Bun ${targetVersion}.` };
 			}
 		}
 
-		const npmWorkflow = require('./npm-publish-workflow');
-		const indexedNpm = Buffer.from((options.readIndexedNpmPublishWorkflow || npmWorkflow.readIndexedNpmPublishWorkflow)(projectRoot));
+		const indexedNpm = Buffer.from(snapshot
+			? snapshot.indexed.get(npmWorkflow.NPM_PUBLISH_WORKFLOW_PATH)
+			: (options.readIndexedNpmPublishWorkflow || npmWorkflow.readIndexedNpmPublishWorkflow)(projectRoot));
 		if (!indexedNpm.equals(Buffer.from(npmWorkflow.renderNpmPublishWorkflow(targetVersion)))) {
 			return { success: false, error: `A staged Bun pin change requires the complete generated workflow set; ${npmWorkflow.NPM_PUBLISH_WORKFLOW_PATH} does not match Bun ${targetVersion}.` };
 		}
+		const testUpdate = (options.resolveTestWorkflowUpdate || testWorkflow.resolveTestWorkflowUpdate)(
+			projectRoot,
+			sourceHead,
+			options,
+		);
+		const indexedTest = Buffer.from(snapshot
+			? snapshot.indexed.get(testWorkflow.TEST_WORKFLOW_PATH)
+			: testUpdate.indexedWorkflow);
+		if (!indexedTest.equals(testUpdate.indexedWorkflow)) {
+			throw new Error(`${testWorkflow.TEST_WORKFLOW_PATH} changed while reading the complete Bun pin snapshot`);
+		}
+		if (!indexedTest.equals(testUpdate.content)) {
+			return { success: false, error: `A staged Bun pin change requires the complete generated workflow set; ${testWorkflow.TEST_WORKFLOW_PATH} does not match Bun ${targetVersion}.` };
+		}
 		return { success: true, sourceVersion, targetVersion };
 	} catch (error) {
 		return { success: false, error: `Could not verify the complete staged Bun pin update: ${error.message}` };
@@ -1091,6 +1290,8 @@ module.exports = {
 	completeNpmPublishWorkflowAuthorization,
 	issueBunWorkflowAuthorization,
 	completeBunWorkflowAuthorization,
+	issueTestWorkflowAuthorization,
+	completeTestWorkflowAuthorization,
 	cancelBunWorkflowBatchAuthorizations,
 	issueGeneratedHarnessClaudeAuthorization,
 	completeGeneratedHarnessClaudeAuthorization,

package/lib/release-readiness.js

@@ -318,20 +318,19 @@ function collectAgentInstructionSurfaces(projectRoot) {
   };
 }
 
-function getRootDocFiles(projectRoot) {
-  return new Set(collectAgentInstructionSurfaces(projectRoot).rootDocFiles);
+function getRootDocFiles(projectRoot, surfaces = collectAgentInstructionSurfaces(projectRoot)) {
+  return new Set(surfaces.rootDocFiles);
 }
 
-function getInstructionPrefixes(projectRoot) {
-  return collectAgentInstructionSurfaces(projectRoot).instructionRoots.map(root => `${root}/`);
+function getInstructionPrefixes(projectRoot, surfaces = collectAgentInstructionSurfaces(projectRoot)) {
+  return surfaces.instructionRoots.map(root => `${root}/`);
 }
 
-function getSkillPrefixes(projectRoot) {
-  return collectAgentInstructionSurfaces(projectRoot).skillRoots.map(root => `${root}/`);
+function getSkillPrefixes(projectRoot, surfaces = collectAgentInstructionSurfaces(projectRoot)) {
+  return surfaces.skillRoots.map(root => `${root}/`);
 }
 
-function getDefaultScanRoots(projectRoot) {
-  const surfaces = collectAgentInstructionSurfaces(projectRoot);
+function getDefaultScanRoots(projectRoot, surfaces = collectAgentInstructionSurfaces(projectRoot)) {
   return [
     ...new Set([
       ...surfaces.rootDocFiles,
@@ -342,18 +341,18 @@ function getDefaultScanRoots(projectRoot) {
   ];
 }
 
-function isTextFile(relativePath, projectRoot) {
+function isTextFile(relativePath, projectRoot, surfaces = collectAgentInstructionSurfaces(projectRoot)) {
   const basename = path.basename(relativePath);
   if (basename.endsWith('.test.js')) {
     return false;
   }
-  if (getRootDocFiles(projectRoot).has(relativePath) || basename === 'lefthook.yml') {
+  if (getRootDocFiles(projectRoot, surfaces).has(relativePath) || basename === 'lefthook.yml') {
     return true;
   }
   return TEXT_EXTENSIONS.has(path.extname(relativePath));
 }
 
-function walkFiles(projectRoot, relativeRoot) {
+function walkFiles(projectRoot, relativeRoot, surfaces = collectAgentInstructionSurfaces(projectRoot)) {
   const rootPath = absolutePath(projectRoot, relativeRoot);
   if (!fs.existsSync(rootPath)) {
     return [];
@@ -362,7 +361,7 @@ function walkFiles(projectRoot, relativeRoot) {
   const stat = fs.statSync(rootPath);
   if (stat.isFile()) {
     const normalized = toRepoPath(relativeRoot);
-    return isTextFile(normalized, projectRoot) && !shouldSkipRelativePath(normalized) ? [normalized] : [];
+    return isTextFile(normalized, projectRoot, surfaces) && !shouldSkipRelativePath(normalized) ? [normalized] : [];
   }
 
   const files = [];
@@ -380,8 +379,8 @@ function walkFiles(projectRoot, relativeRoot) {
     }
 
     if (entry.isDirectory()) {
-      files.push(...walkFiles(projectRoot, relativePath));
-    } else if (entry.isFile() && isTextFile(relativePath, projectRoot)) {
+      files.push(...walkFiles(projectRoot, relativePath, surfaces));
+    } else if (entry.isFile() && isTextFile(relativePath, projectRoot, surfaces)) {
       files.push(relativePath);
     }
   }
@@ -389,7 +388,7 @@ function walkFiles(projectRoot, relativeRoot) {
   return files;
 }
 
-function readSyncManifestScanRoots(projectRoot) {
+function readSyncManifestScanRoots(projectRoot, surfaces = collectAgentInstructionSurfaces(projectRoot)) {
   const manifestPath = absolutePath(projectRoot, '.forge/sync-manifest.json');
   if (!fs.existsSync(manifestPath)) {
     return [];
@@ -406,7 +405,7 @@ function readSyncManifestScanRoots(projectRoot) {
       .filter(file => (
         file.length > 0 &&
         isSafeRepoPath(projectRoot, file) &&
-        isTextFile(file, projectRoot)
+        isTextFile(file, projectRoot, surfaces)
       ));
   } catch (_error) {
     return [];
@@ -426,22 +425,22 @@ function normalizeScanRoot(root) {
   return normalizeRepoPath(root).replace(/[/\\]+$/, '');
 }
 
-function getScanRoots(projectRoot, options = {}) {
-  const roots = options.scanRoots || getDefaultScanRoots(projectRoot);
+function getScanRoots(projectRoot, options = {}, surfaces = collectAgentInstructionSurfaces(projectRoot)) {
+  const roots = options.scanRoots || getDefaultScanRoots(projectRoot, surfaces);
   return [
     ...new Set(
-      [...roots, ...readSyncManifestScanRoots(projectRoot)]
+      [...roots, ...readSyncManifestScanRoots(projectRoot, surfaces)]
         .map(normalizeScanRoot)
         .filter(Boolean),
     ),
   ];
 }
 
-function isInstructionPath(relativePath, projectRoot) {
-  return getInstructionPrefixes(projectRoot).some(prefix => relativePath.startsWith(prefix));
+function isInstructionPath(relativePath, projectRoot, surfaces = collectAgentInstructionSurfaces(projectRoot)) {
+  return getInstructionPrefixes(projectRoot, surfaces).some(prefix => relativePath.startsWith(prefix));
 }
 
-function classifyGroup(relativePath, projectRoot) {
+function classifyGroup(relativePath, projectRoot, surfaces = collectAgentInstructionSurfaces(projectRoot)) {
   if (
     relativePath === 'lefthook.yml' ||
     relativePath.startsWith('.forge/hooks/') ||
@@ -451,7 +450,7 @@ function classifyGroup(relativePath, projectRoot) {
   }
 
   if (
-    getSkillPrefixes(projectRoot).some(prefix => relativePath.startsWith(prefix)) ||
+    getSkillPrefixes(projectRoot, surfaces).some(prefix => relativePath.startsWith(prefix)) ||
     relativePath.startsWith('packages/skills/')
   ) {
     return 'skills';
@@ -463,8 +462,8 @@ function classifyGroup(relativePath, projectRoot) {
 
   if (
     relativePath.startsWith('docs/') ||
-    getRootDocFiles(projectRoot).has(relativePath) ||
-    isInstructionPath(relativePath, projectRoot)
+    getRootDocFiles(projectRoot, surfaces).has(relativePath) ||
+    isInstructionPath(relativePath, projectRoot, surfaces)
   ) {
     return 'docs';
   }
@@ -534,11 +533,16 @@ function trackedRepoFiles(projectRoot) {
 }
 
 function auditBdCallSites(projectRoot, options = {}) {
-  const roots = getScanRoots(projectRoot, options);
+  const surfaces = collectAgentInstructionSurfaces(projectRoot);
+  return auditBdCallSitesWithSurfaces(projectRoot, options, surfaces);
+}
+
+function auditBdCallSitesWithSurfaces(projectRoot, options, surfaces) {
+  const roots = getScanRoots(projectRoot, options, surfaces);
   // Only audit git-tracked files, so untracked working-tree pollution (e.g. a concurrent
   // test's temp files under a scan root) can't perturb the census (issue 1d4077d8).
   const tracked = trackedRepoFiles(projectRoot);
-  const files = [...new Set(roots.flatMap(root => walkFiles(projectRoot, root)))]
+  const files = [...new Set(roots.flatMap(root => walkFiles(projectRoot, root, surfaces)))]
     .filter(relativePath => !tracked || tracked.has(normalizeRepoPath(relativePath)))
     .sort((left, right) => left.localeCompare(right));
   const groups = newGroupedAudit();
@@ -559,7 +563,7 @@ function auditBdCallSites(projectRoot, options = {}) {
       }
     }
 
-    addCallSites(groups, classifyGroup(relativePath, projectRoot), relativePath, lineEntries);
+    addCallSites(groups, classifyGroup(relativePath, projectRoot, surfaces), relativePath, lineEntries);
   }
 
   return {
@@ -578,13 +582,17 @@ function auditBdCallSites(projectRoot, options = {}) {
 // 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)) {
+  if (!relativePath || shouldSkipRelativePath(relativePath)) {
+    return false;
+  }
+  const surfaces = collectAgentInstructionSurfaces(projectRoot);
+  if (!isTextFile(relativePath, projectRoot, surfaces)) {
     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)
+  return getScanRoots(projectRoot, options, surfaces)
     .some(root => {
       // walkFiles applies no directory skips to a root that is itself a file.
       if (relativePath === root) {
@@ -738,8 +746,11 @@ function commandModuleHasRegistryContract(projectRoot, name) {
     hasRegistryCommandHandler(findObjectMember(exportedObject, 'handler'), bindings.functions);
 }
 
-function isD20HotPath(relativePath, projectRoot) {
-  const surfaces = collectAgentInstructionSurfaces(projectRoot);
+function isD20HotPath(
+  relativePath,
+  projectRoot,
+  surfaces = collectAgentInstructionSurfaces(projectRoot),
+) {
   const hotPathFiles = new Set([
     ...D20_HOT_PATH_FILES,
     ...surfaces.rootDocFiles,
@@ -754,14 +765,18 @@ function isD20HotPath(relativePath, projectRoot) {
     hotPathPrefixes.some(prefix => relativePath.startsWith(prefix));
 }
 
-function flattenHotPathEvidence(audit, projectRoot) {
+function flattenHotPathEvidence(
+  audit,
+  projectRoot,
+  surfaces = collectAgentInstructionSurfaces(projectRoot),
+) {
   const files = [];
   for (const group of GROUPS) {
     files.push(...audit.groups[group].files);
   }
 
   return files
-    .filter(file => isD20HotPath(file.path, projectRoot))
+    .filter(file => isD20HotPath(file.path, projectRoot, surfaces))
     .filter(Boolean)
     .map(file => ({
       path: file.path,
@@ -1779,8 +1794,8 @@ function missingArtifactEvidence(relativePath) {
   return [{ path: relativePath, missing: true }];
 }
 
-function hotPathBlocker(audit, projectRoot) {
-  const hotPathEvidence = flattenHotPathEvidence(audit, projectRoot);
+function hotPathBlocker(audit, projectRoot, surfaces) {
+  const hotPathEvidence = flattenHotPathEvidence(audit, projectRoot, surfaces);
   if (hotPathEvidence.length > 0) {
     return {
       id: 'bd-hot-path-issue-commands',
@@ -1966,9 +1981,9 @@ function freshCloneBlocker(projectRoot) {
   return null;
 }
 
-function buildBlockers(projectRoot, audit) {
+function buildBlockers(projectRoot, audit, surfaces) {
   return [
-    hotPathBlocker(audit, projectRoot),
+    hotPathBlocker(audit, projectRoot, surfaces),
     auditArtifactBlocker(projectRoot, audit),
     issueSurfaceBlocker(projectRoot),
     primeBlocker(projectRoot),
@@ -1982,6 +1997,7 @@ function buildBlockers(projectRoot, audit) {
 
 function buildReadinessReport(projectRoot, options = {}) {
   const target = options.target || SUPPORTED_TARGET;
+  const surfaces = collectAgentInstructionSurfaces(projectRoot);
   // Accept prerelease variants (0.1.0-beta.1, 0.1.0-rc.1, …) against their base version's
   // readiness profile — a beta's readiness content is identical to its release.
   const baseTarget = String(target).split('-')[0];
@@ -1995,12 +2011,12 @@ function buildReadinessReport(projectRoot, options = {}) {
         detail: `Unsupported release readiness target: ${target}. Supported target: ${SUPPORTED_TARGET} (prerelease suffixes like -beta.1 are accepted).`,
         evidence: [],
       }],
-      audit: auditBdCallSites(projectRoot, options),
+      audit: auditBdCallSitesWithSurfaces(projectRoot, options, surfaces),
     };
   }
 
-  const audit = auditBdCallSites(projectRoot, options);
-  const blockers = buildBlockers(projectRoot, audit);
+  const audit = auditBdCallSitesWithSurfaces(projectRoot, options, surfaces);
+  const blockers = buildBlockers(projectRoot, audit, surfaces);
 
   return {
     success: blockers.length === 0,

package/lib/shell-utils.js

@@ -13,6 +13,7 @@ const path = require('node:path');
 // (spawnSync ENOENT, kernel issue 9997d516) and patched Node refuses .cmd/.bat
 // without shell:true (CVE-2024-27980).
 const WINDOWS_DIRECT_SPAWN_EXTS = new Set(['.exe', '.com']);
+const executableResolutionCache = new Map();
 
 // Conservative allowlist for tokens executed through cmd.exe. Blocks every cmd
 // metacharacter (& | < > ^ % ! " ' ` ( ) ; and whitespace) so shell execution
@@ -56,6 +57,13 @@ function resolveWindowsSpawnSpec(command, candidates) {
   return { file: command, shell: true };
 }
 
+function windowsEnvironmentValue(environment, name) {
+  const key = Object.keys(environment)
+    .sort((left, right) => (left < right ? -1 : left > right ? 1 : 0))
+    .find((candidate) => candidate.toUpperCase() === name);
+  return key ? environment[key] : '';
+}
+
 /**
  * Securely execute a command with PATH validation.
  * Mitigates SonarCloud S4036: Ensures executables are from trusted locations.
@@ -71,29 +79,47 @@ function secureExecFileSync(command, args = [], options = {}) {
     _execFileSync = execFileSync,
     _spawnSync = spawnSync,
     _platform = process.platform,
+    _resolutionCache = _spawnSync === spawnSync ? executableResolutionCache : null,
     ...execOptions
   } = options;
 
   const isWindows = _platform === 'win32';
   const pathResolver = isWindows ? 'where.exe' : 'which';
+  const commandEnv = execOptions.env || process.env;
+  const lookupDirectory = isWindows ? path.resolve(execOptions.cwd ?? process.cwd()) : undefined;
+  const cacheKey = isWindows && _resolutionCache
+    ? [
+      _platform,
+      command,
+      windowsEnvironmentValue(commandEnv, 'PATH'),
+      windowsEnvironmentValue(commandEnv, 'PATHEXT'),
+      lookupDirectory,
+    ].join('\0')
+    : null;
 
-  let candidates = [];
-  try {
-    // Resolve command's full path to validate it's in a trusted location
-    const result = _spawnSync(pathResolver, [command], {
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore']
-    });
+  let candidates = cacheKey ? _resolutionCache.get(cacheKey) : null;
+  if (!candidates) {
+    candidates = [];
+    try {
+      // Resolve command's full path to validate it's in a trusted location.
+      const result = _spawnSync(pathResolver, [command], {
+        cwd: lookupDirectory,
+        encoding: 'utf8',
+        env: commandEnv,
+        stdio: ['ignore', 'pipe', 'ignore']
+      });
 
-    if (result.status === 0 && result.stdout) {
-      // Handle both CRLF (Windows) and LF (Unix) line endings
-      candidates = result.stdout
-        .trim()
-        .split(/\r?\n/)
-        .map((line) => line.trim())
-        .filter(Boolean);
+      if (result.status === 0 && result.stdout) {
+        // Handle both CRLF (Windows) and LF (Unix) line endings
+        candidates = result.stdout
+          .trim()
+          .split(/\r?\n/)
+          .map((line) => line.trim())
+          .filter(Boolean);
+        if (cacheKey && candidates.length > 0) _resolutionCache.set(cacheKey, candidates);
+      }
+    } catch (_err) { // NOSONAR - S2486: Intentionally ignored; falls back to direct command execution below
     }
-  } catch (_err) { // NOSONAR - S2486: Intentionally ignored; falls back to direct command execution below
   }
 
   if (isWindows) {