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

package/lib/agents-config.js

@@ -93,6 +93,10 @@ Forge currently supports Claude Code, Codex, and Cursor. Hermes support is plann
 - **Codex** - OpenAI's CLI agent, skills-based workflow
 - **Cursor** - IDE-integrated, native Plan/Ask/Debug modes
 
+## Skill Dispatch (auto-trigger)
+
+Before ANY response — including clarifying questions or exploring the codebase — if there is even a 1% chance a Forge skill applies, invoke it, then announce \`Using [skill] to [purpose]\`. Invoke the \`using-forge\` dispatch skill (auto-discovered from your agent's own skills — Forge setup installs it into each harness's skills dir; it carries the 1%-rule and routing table), or run \`forge skill for "<situation>"\` for the deterministic best-fit skill. This is agent-agnostic — never branch on harness identity.
+
 ## Quick Start
 
 \`\`\`bash
@@ -962,6 +966,7 @@ Choose based on server documentation.
 module.exports = {
   detectProjectMetadata,
   generateAgentsMd,
+  generateAgentsMdContent,
   generateCursorConfig,
   generateArchitectureDoc,
   generateConfigurationDoc,

package/lib/audit-evidence.js

@@ -1,6 +1,16 @@
-const { execFileSync } = require('node:child_process');
-const fs = require('node:fs');
 const path = require('node:path');
+const { randomUUID } = require('node:crypto');
+const { appendCappedJsonlRecord } = require('./capped-jsonl-log');
+
+/**
+ * Subagent evidence lands in the local append-only log D25 specifies, now that
+ * the Beads audit CLI is retired along with the rest of the Beads runtime. The
+ * log is the only copy of an entry, so a record carries the prompt and response
+ * the Beads entry used to hold; it is capped like the protected-state log so a
+ * long dev run cannot grow it unbounded.
+ */
+const AUDIT_EVIDENCE_LOG = '.forge/log.jsonl';
+const AUDIT_EVIDENCE_MAX_RECORDS = 500;
 
 const VERDICT_LABELS = {
 	PASS: 'good',
@@ -40,15 +50,6 @@ const SECRET_TEXT_PATTERNS = [
 	/\bsk-[A-Za-z0-9_-]{8,}\b/g,
 ];
 
-function defaultRunCommand(command, args, options = {}) {
-	return execFileSync(command, args, {
-		cwd: options.cwd || process.cwd(),
-		encoding: 'utf8',
-		input: options.input,
-		timeout: options.timeout || 120000,
-	});
-}
-
 function redactString(value) {
 	return SECRET_TEXT_PATTERNS.reduce(
 		(current, entry) => {
@@ -132,96 +133,62 @@ function buildSubagentAuditPayload(event) {
 	};
 }
 
-function parseRecordId(output, { requireJson = false } = {}) {
-	if (!output) return null;
+/**
+ * Best-effort: a failed append is reported back to the caller, never thrown, so
+ * losing the evidence can never fail the command that produced it.
+ */
+function appendAuditRecord(record, options) {
+	const logPath = path.resolve(options.cwd || process.cwd(), AUDIT_EVIDENCE_LOG);
+	const appendRecord = options.appendRecord || appendCappedJsonlRecord;
+
 	try {
-		const parsed = JSON.parse(output);
-		return typeof parsed.id === 'string' ? parsed.id : null;
-	} catch (_error) {
-		if (requireJson) return null;
-		const match = /\bint-[A-Za-z0-9_-]+\b/.exec(String(output));
-		return match ? match[0] : null;
+		appendRecord(logPath, record, options.maxRecords || AUDIT_EVIDENCE_MAX_RECORDS);
+		return { success: true, logPath };
+	} catch (error) {
+		return { success: false, logPath, error: error.message };
 	}
 }
 
-function hasAuditMetaJsonSupport(runCommand = defaultRunCommand, options = {}) {
-	const output = runCommand('bd', ['audit', 'record', '--help'], options);
-	return String(output).includes('--meta-json');
-}
-
-function writeFallbackMetadata(payload, entryId, options) {
-	if (!entryId || !payload.metadata || Object.keys(payload.metadata).length === 0) {
-		return null;
-	}
-
-	const cwd = options.cwd || process.cwd();
-	const fsImpl = options.fs || fs;
-	const forgeDir = path.join(cwd, '.forge').replace(/\\/g, '/');
-	const logPath = path.join(forgeDir, 'log.jsonl').replace(/\\/g, '/');
-	const line = {
+function buildAuditEvidenceRecord(payload, entryId, recordedAt) {
+	return {
 		kind: 'forge.auditEvidence',
-		sourceOfTruth: 'beads',
-		beadsEntryId: entryId,
+		sourceOfTruth: 'forge_log',
+		entryId,
+		recordedAt,
 		command: redact(payload.command),
+		issueId: redact(payload.issueId),
 		role: redact(payload.role),
 		phase: redact(payload.phase),
 		taskId: redact(payload.taskId),
 		taskTitle: redact(payload.taskTitle),
-		metadata: redact(payload.metadata),
+		model: redact(payload.model),
+		verdict: payload.verdict,
+		// Already redacted by buildSubagentAuditPayload.
+		prompt: payload.prompt,
+		response: payload.response,
+		metadata: payload.metadata,
 	};
-
-	try {
-		fsImpl.mkdirSync(forgeDir, { recursive: true });
-		fsImpl.appendFileSync(logPath, `${JSON.stringify(line)}\n`);
-		return { path: logPath, line };
-	} catch (error) {
-		return { path: logPath, line, skipped: true, error: error.message };
-	}
 }
 
 function recordSubagentAuditEvent(event, options = {}) {
 	const payload = buildSubagentAuditPayload(event);
-	const runCommand = options.runCommand || defaultRunCommand;
-	const metaJsonSupported =
-		typeof options.metaJsonSupported === 'boolean'
-			? options.metaJsonSupported
-			: hasAuditMetaJsonSupport(runCommand, { cwd: options.cwd || process.cwd() });
-	const args = [
-		'audit',
-		'record',
-		'--json',
-		'--kind',
-		'llm_call',
-	];
-
-	if (payload.issueId) {
-		args.push('--issue-id', payload.issueId);
-	}
-
-	args.push(
-		'--model',
-		payload.model,
-		'--prompt',
-		payload.prompt,
-		'--response',
-		payload.response,
+	const entryId = (options.newId || randomUUID)();
+	const record = buildAuditEvidenceRecord(
+		payload,
+		entryId,
+		options.now || new Date().toISOString(),
 	);
+	const written = appendAuditRecord(record, options);
 
-	if (metaJsonSupported && Object.keys(payload.metadata).length > 0) {
-		args.push('--meta-json', JSON.stringify(payload.metadata));
-	}
-
-	const output = runCommand('bd', args, { cwd: options.cwd || process.cwd() });
-	const entryId = parseRecordId(output, { requireJson: true });
-	const fallback = metaJsonSupported ? null : writeFallbackMetadata(payload, entryId, options);
-
-	return {
-		success: Boolean(entryId),
-		entryId,
-		output,
+	const result = {
+		success: written.success,
+		entryId: written.success ? entryId : null,
+		record,
 		payload,
-		fallback,
+		logPath: written.logPath,
 	};
+	if (!written.success) result.error = written.error;
+	return result;
 }
 
 function labelSubagentAuditEvent(entryId, event, options = {}) {
@@ -233,36 +200,29 @@ function labelSubagentAuditEvent(entryId, event, options = {}) {
 		return { skipped: true };
 	}
 
-	const runCommand = options.runCommand || defaultRunCommand;
-	const reason = `${role} verdict: ${verdict}`;
-	let output;
-	try {
-		output = runCommand('bd', [
-			'audit',
-			'label',
-			entryId,
-			'--json',
-			'--label',
-			label,
-			'--reason',
-			reason,
-		], { cwd: options.cwd || process.cwd() });
-	} catch (error) {
-		return {
-			success: false,
-			label,
-			error: error.message,
-		};
-	}
-
-	const labeledEntryId = parseRecordId(output, { requireJson: true });
+	// A label is its own record rather than a rewrite of the recorded entry: the
+	// log is append-only, so a verdict is read by joining on entryId.
+	const record = {
+		kind: 'forge.auditEvidenceLabel',
+		sourceOfTruth: 'forge_log',
+		entryId,
+		recordedAt: options.now || new Date().toISOString(),
+		role,
+		verdict,
+		label,
+		reason: `${role} verdict: ${verdict}`,
+	};
+	const written = appendAuditRecord(record, options);
 
-	return {
-		success: labeledEntryId === entryId,
+	const result = {
+		success: written.success,
 		label,
-		entryId: labeledEntryId,
-		output,
+		entryId: written.success ? entryId : null,
+		record,
+		logPath: written.logPath,
 	};
+	if (!written.success) result.error = written.error;
+	return result;
 }
 
 function recordAndLabelSubagentAuditEvent(event, options = {}) {
@@ -272,11 +232,12 @@ function recordAndLabelSubagentAuditEvent(event, options = {}) {
 }
 
 module.exports = {
+	AUDIT_EVIDENCE_LOG,
+	AUDIT_EVIDENCE_MAX_RECORDS,
 	VERDICT_LABELS,
 	buildSubagentAuditPayload,
 	recordSubagentAuditEvent,
 	labelSubagentAuditEvent,
 	recordAndLabelSubagentAuditEvent,
-	hasAuditMetaJsonSupport,
 	redact,
 };

package/lib/capped-jsonl-log.js

@@ -0,0 +1,236 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * The local append-only JSONL sink shared by every Forge log that must survive
+ * without a database handle: the protected-state audit log and the subagent
+ * audit-evidence log. Kept in its own module so both writers get the same
+ * concurrency and cap behaviour instead of a second copy drifting from the first.
+ */
+
+const TRIM_LOCK_ATTEMPTS = 5;
+const TRIM_LOCK_RETRY_MS = 20;
+/**
+ * How many times the trim re-reads the log for records appended since its
+ * snapshot. Each pass copies less than the last, so a small bound is enough to
+ * drain a burst without letting a busy writer keep the rename waiting forever.
+ */
+const TRIM_DELTA_PASSES = 3;
+/**
+ * How many times the trim rewrites the log to get it under the cap. A rewrite
+ * that drained concurrent appends can still sit above it, and one more quiet
+ * pass settles that; the bound stops a relentless writer from pinning the lock.
+ */
+const NEWLINE_BYTE = 0x0a;
+/** The trim rewrite takes milliseconds, so an older lock outlived its process. */
+const TRIM_LOCK_STALE_MS = 5000;
+/**
+ * Another process is using the file. POSIX reports only EEXIST/EBUSY, but
+ * Windows answers EPERM/EACCES both for a lock whose delete is still pending and
+ * for a replace of a log some other writer holds open.
+ */
+const FILE_CONTENDED_CODES = new Set(['EEXIST', 'EPERM', 'EACCES', 'EBUSY']);
+
+function sleepSync(ms) {
+	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function lockHeldSinceMs(lockPath) {
+	try {
+		return fs.lstatSync(lockPath).mtimeMs;
+	} catch (error) {
+		if (error.code === 'ENOENT') return null;
+		throw error;
+	}
+}
+
+function acquireTrimLock(lockPath) {
+	for (let attempt = 0; attempt < TRIM_LOCK_ATTEMPTS; attempt += 1) {
+		try {
+			return fs.openSync(lockPath, 'wx');
+		} catch (error) {
+			if (!FILE_CONTENDED_CODES.has(error.code)) throw error;
+
+			const heldSince = lockHeldSinceMs(lockPath);
+			if (heldSince !== null && Date.now() - heldSince > TRIM_LOCK_STALE_MS) {
+				try {
+					fs.unlinkSync(lockPath);
+				} catch {
+					// Another writer reclaimed it first; retry against theirs.
+				}
+				continue;
+			}
+
+			sleepSync(TRIM_LOCK_RETRY_MS);
+		}
+	}
+
+	return null;
+}
+
+function releaseTrimLock(handle, lockPath) {
+	try {
+		fs.closeSync(handle);
+	} catch {
+		// Already closed.
+	}
+	try {
+		fs.unlinkSync(lockPath);
+	} catch {
+		// Already reclaimed as stale.
+	}
+}
+
+/**
+ * Reads the log as whole records plus the byte offset they end at, so a later
+ * read can resume exactly where this one stopped. A trailing partial line is
+ * excluded from both: it belongs to an append still in flight, and cutting the
+ * offset at the last newline keeps the resume point on a record boundary.
+ */
+function snapshotJsonl(logPath) {
+	let raw;
+	try {
+		raw = fs.readFileSync(logPath);
+	} catch (error) {
+		if (error.code !== 'ENOENT') throw error;
+		return { lines: [], size: 0 };
+	}
+
+	const size = raw.lastIndexOf(NEWLINE_BYTE) + 1;
+	return { lines: raw.subarray(0, size).toString('utf8').split('\n').filter(Boolean), size };
+}
+
+/** The whole records appended past `offset`, or null when there are none yet. */
+function readAppendsSince(logPath, offset) {
+	let size;
+	try {
+		// Almost every trim runs with nobody appending, so answer from a stat alone
+		// and keep the extra work off the lock in the common case.
+		size = fs.statSync(logPath).size;
+	} catch (error) {
+		if (error.code === 'ENOENT') return null;
+		throw error;
+	}
+	if (size <= offset) return null;
+
+	let handle;
+	try {
+		handle = fs.openSync(logPath, 'r');
+	} catch (error) {
+		if (error.code === 'ENOENT') return null;
+		throw error;
+	}
+
+	try {
+		const buffer = Buffer.alloc(size - offset);
+		const read = fs.readSync(handle, buffer, 0, buffer.length, offset);
+		const end = buffer.subarray(0, read).lastIndexOf(NEWLINE_BYTE) + 1;
+		if (end === 0) return null;
+
+		const bytes = buffer.subarray(0, end);
+		return { bytes, records: bytes.toString('utf8').split('\n').filter(Boolean).length };
+	} finally {
+		fs.closeSync(handle);
+	}
+}
+
+/**
+ * One rewrite of the log down to its cap, returning the record count it left
+ * behind — or null when a contended rename made it give up. Records drained from
+ * concurrent appenders ride above the cap, so the caller has to check.
+ * Must be called with the trim lock held.
+ */
+function rewriteToCap(logPath, maxRecords, pendingLine = null) {
+	const snapshot = snapshotJsonl(logPath);
+	if (snapshot.lines.length < maxRecords && pendingLine !== null) {
+		fs.appendFileSync(logPath, `${pendingLine}\n`, 'utf8');
+		return snapshot.lines.length + 1;
+	}
+	if (snapshot.lines.length <= maxRecords && pendingLine === null) return snapshot.lines.length;
+
+	const candidates = pendingLine === null ? snapshot.lines : [...snapshot.lines, pendingLine];
+	const kept = candidates.slice(-maxRecords);
+	// Write-then-rename so a crash mid-trim cannot leave a torn log behind.
+	const tempPath = `${logPath}.${process.pid}.tmp`;
+	fs.writeFileSync(tempPath, `${kept.join('\n')}\n`, 'utf8');
+
+	// Appenders hold no lock, so records keep landing in the log this rename is
+	// about to replace. Copy them onto the temp file first — repeatedly, since
+	// the copy itself takes time a writer can append into. Nothing heavier goes
+	// between the last copy and the rename, which is what keeps the window small.
+	let offset = snapshot.size;
+	let drained = 0;
+	for (let pass = 0; pass < TRIM_DELTA_PASSES; pass += 1) {
+		const appended = readAppendsSince(logPath, offset);
+		if (appended === null) break;
+		fs.appendFileSync(tempPath, appended.bytes);
+		offset += appended.bytes.length;
+		drained += appended.records;
+	}
+	if (pendingLine !== null && drained > 0) {
+		const prepared = snapshotJsonl(tempPath).lines;
+		fs.writeFileSync(tempPath, `${prepared.slice(-maxRecords).join('\n')}\n`, 'utf8');
+	}
+
+	try {
+		fs.renameSync(tempPath, logPath);
+	} catch (error) {
+		// Another writer still has the log open for its append. Same answer as
+		// losing the lock race: drop this trim, the next writer will do it.
+		if (!FILE_CONTENDED_CODES.has(error.code)) throw error;
+		fs.rmSync(tempPath, { force: true });
+		return null;
+	}
+	return pendingLine === null ? kept.length + drained : Math.min(kept.length + drained, maxRecords);
+}
+
+function appendAtCap(logPath, recordLine, maxRecords) {
+	const snapshot = snapshotJsonl(logPath);
+
+	const lockPath = `${logPath}.lock`;
+	const lock = acquireTrimLock(lockPath);
+	// A held lock means another writer is already trimming. These logs are
+	// best-effort sinks on the hot path of a hook or a command, so skip and let
+	// the next writer past the cap trim instead of blocking the caller.
+	if (lock === null) {
+		fs.appendFileSync(logPath, `${recordLine}\n`, 'utf8');
+		return snapshot.lines.length + 1;
+	}
+
+	try {
+		const rewritten = rewriteToCap(logPath, maxRecords, recordLine);
+		if (rewritten === null) {
+			fs.appendFileSync(logPath, `${recordLine}\n`, 'utf8');
+			return snapshotJsonl(logPath).lines.length;
+		}
+		return rewritten;
+	} finally {
+		releaseTrimLock(lock, lockPath);
+	}
+}
+
+/**
+ * Below the cap, O_APPEND keeps each small record atomic. At the cap, the new
+ * record is prepared inside the locked replacement so failure cannot be
+ * reported after the authorization has already landed in the live log.
+ *
+ * That leaves one window, and the trim narrows rather than closes it: records
+ * appended after the trim's snapshot are drained onto the replacement file right
+ * before the rename, so only a record landing between the final drain and the
+ * rename syscall itself can still be lost. Closing it completely would mean
+ * locking every append, which these hot-path sinks do not pay for.
+ */
+function appendCappedJsonlRecord(logPath, record, maxRecords) {
+	fs.mkdirSync(path.dirname(logPath), { recursive: true });
+	const recordLine = JSON.stringify(record);
+	const snapshot = snapshotJsonl(logPath);
+	if (snapshot.lines.length < maxRecords) {
+		fs.appendFileSync(logPath, `${recordLine}\n`, 'utf8');
+		return snapshot.lines.length + 1;
+	}
+	return appendAtCap(logPath, recordLine, maxRecords);
+}
+
+module.exports = {
+	appendCappedJsonlRecord,
+};

package/lib/commands/_issue.js

@@ -2,7 +2,6 @@
 
 const { runIssueOperation: defaultRunIssueOperation } = require('../forge-issues');
 const { resolveIssueBackend, hasExplicitBackendSignal, shouldUseKernelBroker } = require('../issue-backend');
-const { maybeWarnUnmigratedBeads } = require('../beads-nudge');
 const {
   ISSUE_COMMAND_SCHEMA_VERSION,
   ISSUE_COMMAND_ERROR_SCHEMA_VERSION,
@@ -17,11 +16,10 @@ const { checkReadFirst } = require('../grounding/read-first');
 const { recordContextLoaded } = require('../grounding/context-events');
 
 // The Forge issue command surface. Each subcommand routes through the shared
-// runIssueOperation, which selects the active backend (Kernel by --kernel /
-// --issue-backend kernel / FORGE_ISSUE_BACKEND=kernel; Beads otherwise) and performs
-// any backend-specific argument translation. This module therefore carries NO direct
-// issue-tracker invocation or argv translation — those live in the backend
-// abstraction (lib/forge-issues.js + the issue adapters).
+// runIssueOperation, which dispatches to the Forge Kernel — the only issue backend.
+// This module therefore carries NO direct issue-tracker invocation or argv
+// translation — those live in the backend abstraction (lib/forge-issues.js + the
+// kernel issue adapter).
 const SUBCOMMANDS = {
   create: {
     description: 'Create an issue via Forge',
@@ -67,10 +65,8 @@ const SUBCOMMANDS = {
     description: 'Show issue statistics via Forge',
     usage: 'forge issue stats [flags]',
   },
-  // KAP-7: derived read queries. The backend abstraction maps each to its tracker
-  // equivalent (the Kernel passes the operation name through unchanged; the Beads
-  // backend maps each to its passthrough subcommand). They are READS, so they are
-  // intentionally NOT in WRITE_SUBCOMMANDS.
+  // KAP-7: derived read queries. The Kernel passes the operation name through
+  // unchanged. They are READS, so they are intentionally NOT in WRITE_SUBCOMMANDS.
   blocked: {
     description: 'Show blocked issues via Forge',
     usage: 'forge issue blocked [flags]',
@@ -106,9 +102,7 @@ const SUBCOMMANDS = {
     usage: 'forge issue owns <id> [--json]',
   },
   // Active-lease listing (kernel issue 7dc229d4). A bare passthrough to the Kernel
-  // lease table (kernel_claims); Beads has no lease table to enumerate, so
-  // forge-issues.js rejects the Beads path explicitly. A READ, so intentionally NOT
-  // in WRITE_SUBCOMMANDS.
+  // lease table (kernel_claims). A READ, so intentionally NOT in WRITE_SUBCOMMANDS.
   claims: {
     description: 'Show active issue leases (claims) via Forge',
     usage: 'forge issue claims [--json]',
@@ -389,8 +383,7 @@ function formatIssueHelp() {
 }
 
 // Map a CLI subcommand to the backend operation name. `dep` fans out to
-// `dep.<action>`; every other subcommand uses its own name (the backend performs
-// any tracker-specific translation, e.g. Beads claim -> `update <id> --claim`).
+// `dep.<action>`; every other subcommand uses its own name.
 function resolveIssueOperation(subcommand, args) {
   if (subcommand === 'dep') {
     return `dep.${normalizeArgs(args)[0]}`;
@@ -400,10 +393,8 @@ function resolveIssueOperation(subcommand, args) {
 
 // The Kernel create payload (buildCreatePayload) reads only the --title flag, so a
 // bare leading positional (`forge create "title"`) would be ignored and the title
-// would default to the minted UUID. For parity on the KERNEL PATH ONLY, translate a
-// single leading bare positional into `--title <value>` when no explicit
-// --title/--title= is present. The Beads backend keeps its native positional
-// handling (this never runs for the Beads path).
+// would default to the minted UUID. Translate a single leading bare positional into
+// `--title <value>` when no explicit --title/--title= is present.
 function withKernelCreateTitle(args) {
   const hasTitle = args.some(
     arg => arg === '--title' || (typeof arg === 'string' && arg.startsWith('--title=')),
@@ -454,10 +445,12 @@ function validateDepArgs(args) {
   return null;
 }
 
-// Resolve the active issue backend (kernel|beads) and thread it into opts so the
-// shared runIssueOperation deps see it. OPT-IN ONLY: opts is left byte-identical
-// when no explicit signal is present (env/config/explicit), preserving the Beads
-// default path. A copy is returned — the caller's opts object is never mutated.
+// Normalize any explicit issue-backend signal and thread the resolved value into
+// opts so the shared runIssueOperation deps see it. OPT-IN ONLY: opts is left
+// byte-identical when no explicit signal is present (env/config/explicit), so the
+// no-signal path stays untouched. A copy is returned — the caller's opts object is
+// never mutated. A retired value (`beads`) warns here with the migrate pointer and
+// resolves to the kernel.
 function withResolvedIssueBackend(projectRoot, opts = {}) {
   const env = opts.env || process.env;
   const signalContext = { deps: opts, env, projectRoot };
@@ -479,13 +472,13 @@ function withResolvedIssueBackend(projectRoot, opts = {}) {
 
 // The Kernel broker returns the issue-command contract shape
 // ({ ok, schema_version, command, data, next_commands } or { ok:false, error })
-// rather than the Beads-style { success, output }. The bin/forge.js result printer
+// rather than the legacy { success, output }. The bin/forge.js result printer
 // keys on `success`/`output`, so a raw kernel contract would render as
 // "Command failed". Normalize ONLY the contract shape (ok defined, success
 // undefined) into { success, output } here, at the command boundary — the kernel
 // contract itself stays untouched. Every other result passes through byte-identical.
 //
-// Response-contract parity (the Beads behavior the Kernel replaced):
+// Response-contract guarantees:
 //   * SUCCESS  → the printed envelope carries `ok:true` (consumers gate on it).
 //   * FAILURE  → the contract `exit_code` is surfaced as `result.exitCode` so the bin
 //                printer exits with the error class's code (not always 1); and on
@@ -609,8 +602,7 @@ function splitLeadingIds(args = []) {
 // which broke envelope parity for multi-id close. `ok` is true only when every id
 // closed; per-id outcomes live in `data.results` and the contract `exit_code` of the
 // first failure is surfaced as `exitCode` so the bin printer exits with the error
-// class's code. KERNEL PATH ONLY: the Beads passthrough keeps its single
-// `close id1 id2 ...` invocation.
+// class's code.
 async function runKernelBatchClose(runner, operation, ids, flags, projectRoot, opts, verifyEnabled = false) {
   const results = [];
   let allSucceeded = true;
@@ -700,13 +692,11 @@ async function runIssueSubcommand(subcommand, args, projectRoot, rawOpts = {}) {
     return { success: false, error: `Unknown issue subcommand '${subcommand}'.\n\n${formatIssueHelp()}` };
   }
 
-  // Backend-agnostic --help short-circuit: print the subcommand's usage and return
-  // BEFORE resolving the backend or dispatching any operation. Without this, a help
-  // request was forwarded to the active backend as an operation arg — absorbed
-  // harmlessly by Beads (which swallowed --help), but broken under the Kernel default:
-  // the plural path failed with a bare "Command failed" and the singular path
-  // SILENTLY minted a junk issue (and could queue a GitHub projection). Help must
-  // never touch a backend.
+  // --help short-circuit: print the subcommand's usage and return BEFORE resolving
+  // the backend or dispatching any operation. Without this, a help request is
+  // forwarded to the Kernel as an operation arg: the plural path fails with a bare
+  // "Command failed" and the singular path SILENTLY mints a junk issue (and could
+  // queue a GitHub projection). Help must never touch a backend.
   if (normalizeArgs(args).some(arg => arg === '--help' || arg === '-h')) {
     return { success: true, output: `${spec.usage}\n\n${spec.description}` };
   }
@@ -749,17 +739,16 @@ async function runIssueSubcommand(subcommand, args, projectRoot, rawOpts = {}) {
     }
   }
 
-  // Both backends are reached through the same runIssueOperation seam. Naming the
-  // injected local `runIssueOperation` keeps the dispatch a literal call to a binding
-  // named `runIssueOperation` (the kernel-evidence gate is syntactic) while still
-  // honoring an injected runner; the `kernelBroker: opts.kernelBroker` passthrough is
-  // a runtime no-op (undefined under Beads) that documents the Kernel-capable surface.
+  // The Kernel is reached through the runIssueOperation seam. Naming the injected
+  // local `runIssueOperation` keeps the dispatch a literal call to a binding named
+  // `runIssueOperation` (the kernel-evidence gate is syntactic) while still honoring
+  // an injected runner.
   const runIssueOperation = opts.runIssueOperation || defaultRunIssueOperation;
   const operation = resolveIssueOperation(subcommand, args);
   const operationArgs = resolveOperationArgs(subcommand, args, opts);
 
-  // Check-after-write (gate.issue_verify): resolved ONCE per invocation, kernel
-  // path only. Reads and the Beads path never trigger a read-back.
+  // Check-after-write (gate.issue_verify): resolved ONCE per invocation. Reads never
+  // trigger a read-back.
   const verifyEnabled = VERIFIED_SUBCOMMANDS.has(subcommand)
     && shouldUseKernelBroker(opts)
     && isIssueVerifyEnabled(projectRoot, opts);
@@ -779,7 +768,7 @@ async function runIssueSubcommand(subcommand, args, projectRoot, rawOpts = {}) {
     projectRoot,
     { ...opts, kernelBroker: opts.kernelBroker },
   );
-  // Verify only a SUCCESSFUL kernel-contract mutation (ok:true, not a Beads
+  // Verify only a SUCCESSFUL kernel-contract mutation (ok:true, not a legacy
   // {success,output} shape). Warn-only: attaches verified/mismatches, never
   // changes the result's success or exit code.
   if (verifyEnabled && result && typeof result === 'object' && result.ok === true && result.success === undefined) {
@@ -787,10 +776,6 @@ async function runIssueSubcommand(subcommand, args, projectRoot, rawOpts = {}) {
   }
   // Best-effort, non-blocking: mirror a stage-transition comment into stage_runs.
   recordStageTransitionFromComment(subcommand, operationArgs, result, opts);
-  // Best-effort, non-blocking: nudge a returning 0.0.10 user whose empty Kernel
-  // read hides an unmigrated legacy issue store (kernel issue a5399f3d). The hint
-  // text lives in lib/beads-nudge.js so this hot path stays token-free.
-  maybeWarnUnmigratedBeads(subcommand, result, projectRoot, rawOpts);
   // Grounding (gate.read_first): a successful `forge show <id>` counts as reading
   // the issue, so append a `context.loaded` event. Best-effort and awaited (a
   // fire-and-forget append could lose the event when the CLI process exits); a