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

package/lib/commands/plan.js

@@ -1,5 +1,5 @@
 /**
- * Plan Command - Beads Integration
+ * Plan Command - Kernel Issue Integration
  * Creates implementation plan after research is complete
  *
  * Security: Uses execFileSync instead of exec/execSync to prevent command injection
@@ -26,15 +26,14 @@ const MAX_FILE_SIZE = 5 * 1024 * 1024; // 5MB
 
 /**
  * Human-readable label for the issue backend that created an issue.
- * Keeps printed output backend-accurate so kernel-created issues are not
- * mislabeled as "Beads".
+ * The kernel is the only backend; anything unresolved prints a neutral label
+ * rather than naming a store the issue did not come from.
  *
- * @param {string} [backend] - Resolved issue backend ('kernel' | 'beads').
- * @returns {string} Display label ('Kernel', 'Beads', or a neutral 'Issue').
+ * @param {string} [backend] - Resolved issue backend ('kernel').
+ * @returns {string} Display label ('Kernel' or a neutral 'Issue').
  * @private
  */
 function issueBackendLabel(backend) {
-	if (backend === 'beads') return 'Beads';
 	if (backend === 'kernel') return 'Kernel';
 	return 'Issue';
 }
@@ -76,7 +75,7 @@ function validateFeatureSlug(slug) {
 }
 
 /**
- * Build the issue description shared by both issue backends (kernel and beads).
+ * Build the issue description used when creating the kernel tracking issue.
  * Strategic scope appends a design-doc pointer derived from a sanitized slug.
  *
  * @param {string} featureName
@@ -247,98 +246,12 @@ function detectScope(researchContent) {
 	};
 }
 
-/**
- * Create Beads issue for the feature
- * Executes `bd create` command with appropriate description based on scope
- *
- * Security: Uses execFileSync (not exec) to prevent command injection
- *
- * @param {string} featureName - Feature name (human-readable)
- * @param {string} researchPath - Research document path (e.g., "docs/research/feature.md")
- * @param {'tactical'|'strategic'} scope - Scope type
- * @returns {{success: boolean, issueId?: string, description?: string, error?: string}} Beads creation result
- * @example
- * const result = createBeadsIssue('Payment Integration', 'docs/research/payment.md', 'strategic');
- * if (result.success) {
- *   console.log('Created issue:', result.issueId);
- * }
- */
-function createBeadsIssue(featureName, researchPath, scope) {
-	if (!featureName || !researchPath) {
-		return {
-			success: false,
-			error: 'Feature name and research path are required',
-		};
-	}
-
-	if (scope !== 'tactical' && scope !== 'strategic') {
-		return {
-			success: false,
-			error: `Invalid scope '${scope}'. Must be 'tactical' or 'strategic'`,
-		};
-	}
-
-	try {
-		const built = buildFeatureIssueDescription(featureName, researchPath, scope);
-		if (built.error) {
-			return { success: false, error: built.error };
-		}
-		const description = built.description;
-
-		// Execute bd create command using execFileSync for safety (OWASP A03)
-		const result = execFileSync(  // NOSONAR S4036 - hardcoded CLI command, no user input, developer tool context
-			'bd',  // NOSONAR S4036 - hardcoded CLI command, no user input, developer tool context
-			['create', `--title=${featureName}`, `--description=${description}`, '--type=feature', '--priority=2'],
-			getExecOptions()
-		);
-
-		// Extract issue ID from output (format: "Created issue: forge-xxx" or "forge-xxx.N" for dotted sub-IDs).
-		// Character class is [a-z0-9] (not [a-zA-Z0-9]) because the /i flag makes A-Z redundant.
-		const createPattern = /Created issue:\s*(forge-[a-z0-9]+(?:\.[a-z0-9]+)*)/i;
-		const fallbackPattern = /(forge-[a-z0-9]+(?:\.[a-z0-9]+)*)/i;
-		const match = createPattern.exec(result) || fallbackPattern.exec(result);
-
-		if (!match) {
-			return {
-				success: false,
-				error: 'Failed to extract issue ID from bd create output\n\nEnsure beads is installed: bunx beads init',
-			};
-		}
-
-		return {
-			success: true,
-			issueId: match[1],
-			description,
-		};
-	} catch (error) {
-		// Check for timeout
-		if (error.killed && error.signal === 'SIGTERM') {
-			return {
-				success: false,
-				error: 'Beads command timed out after 2 minutes.',
-			};
-		}
-
-		// Provide actionable error message
-		const bdNotFound = error.message.includes('ENOENT') || error.message.includes('not found');
-		const errorMsg = bdNotFound
-			? 'beads (bd) command not found. Install with: bunx beads init'
-			: `Failed to create Beads issue: ${error.message}`;
-
-		return {
-			success: false,
-			error: errorMsg,
-		};
-	}
-}
-
 /**
  * Create an issue via the Forge Kernel backend (bd-free).
  *
  * Mirrors `forge issue create` on the kernel: routes through runIssueOperation with
  * the kernel broker instead of shelling out to `bd create`. Used by `forge plan` when
- * the resolved issue backend is the kernel (the default), so planning needs no Beads
- * install. The beads path (createBeadsIssue) is preserved for backend=beads.
+ * the kernel is the only issue backend, so planning needs no bd binary installed.
  *
  * @param {string} featureName
  * @param {string} researchPath
@@ -413,7 +326,7 @@ async function linkExistingIssue(issueId, options = {}) {
 			projectRoot,
 			{
 				issueBackend,
-				useKernelBroker: issueBackend !== 'beads',
+				useKernelBroker: true,
 				kernelBroker: options.kernelBroker,
 			},
 		);
@@ -584,9 +497,9 @@ async function registerBranchIssueLinkage(options, branch, issueId) {
 }
 
 /**
- * Resolve the tracking issue for a plan: LINK an explicit issue, else CREATE via
- * the active backend (the kernel default needs no Beads). Extracted to avoid a
- * nested ternary in executePlan.
+ * Resolve the tracking issue for a plan: LINK an explicit issue, else CREATE in
+ * the kernel (the only issue backend — planning needs no bd binary). Extracted to
+ * avoid a nested ternary in executePlan.
  *
  * @returns {Promise<{success: boolean, issueId?: string, error?: string}>}
  * @private
@@ -595,10 +508,7 @@ async function resolveTrackingIssue({ explicitIssueId, issueBackend, featureName
 	if (explicitIssueId) {
 		return linkExistingIssue(explicitIssueId, { ...options, issueBackend });
 	}
-	if (issueBackend === 'kernel') {
-		return createKernelIssue(featureName, researchPath, scope, options);
-	}
-	return createBeadsIssue(featureName, researchPath, scope);
+	return createKernelIssue(featureName, researchPath, scope, options);
 }
 
 async function createKernelIssue(featureName, researchPath, scope, options = {}) {
@@ -952,14 +862,14 @@ function applyYAGNIFilter({ task, tasks, designDoc } = {}) {
  * Tactical workflow (quick fixes, <1 day):
  * 1. Read research document
  * 2. Detect scope (tactical)
- * 3. Create Beads issue
+ * 3. Create kernel issue
  * 4. Create feature branch
  * → Next: /dev command
  *
  * Strategic workflow (architecture changes, >1 day):
  * 1. Read research document
  * 2. Detect scope (strategic)
- * 3. Create Beads issue with design doc link
+ * 3. Create kernel issue with design doc link
  * 4. Create feature branch
  * → Next: Create design doc, then /dev command
  *
@@ -967,7 +877,7 @@ function applyYAGNIFilter({ task, tasks, designDoc } = {}) {
  * @returns {Promise<{
  *   success: boolean,
  *   scope?: 'tactical'|'strategic',
- *   issueBackend?: 'kernel'|'beads',
+ *   issueBackend?: 'kernel',
  *   issueId?: string,
  *   beadsIssueId?: string,
  *   branchName?: string,
@@ -975,10 +885,10 @@ function applyYAGNIFilter({ task, tasks, designDoc } = {}) {
  *   summary?: string,
  *   nextCommand?: string,
  *   error?: string
- * }>} Execution result. `issueId` is the created issue id under the active
- *   backend; `issueBackend` names that backend. `beadsIssueId` is a deprecated
- *   alias of `issueId` kept for backward compatibility (it does NOT imply the
- *   issue came from Beads — on the kernel path it holds the kernel issue id).
+ * }>} Execution result. `issueId` is the created kernel issue id, and
+ *   `issueBackend` names the backend ('kernel'). `beadsIssueId` is a deprecated
+ *   alias of `issueId` kept for output-shape compatibility — it never implied a
+ *   Beads store and now always holds the kernel issue id.
  * @example
  * const result = await executePlan('Payment Integration');
  * if (result.success) {
@@ -995,7 +905,7 @@ async function executePlan(featureName, options = {}) { // NOSONAR S3776
 	}
 
 	// Resolve the active issue backend (explicit opts > env > .forge/config.yaml >
-	// default 'kernel'). Kernel is bd-free, so planning works with no Beads install.
+	// default 'kernel'). The kernel is bd-free, so planning needs no bd binary.
 	const issueBackend = resolveIssueBackend({
 		deps: options,
 		env: options.env || process.env,
@@ -1031,8 +941,7 @@ async function executePlan(featureName, options = {}) { // NOSONAR S3776
 
 		// Step 3: Resolve the tracking issue. `--issue <id>` LINKS an existing issue
 		// (claim-first flow) instead of creating a duplicate (B4). Otherwise create
-		// via the active backend — kernel (default) routes through the kernel broker
-		// (no bd); beads preserves the bd path.
+		// through the kernel broker (no bd binary involved).
 		const explicitIssueId = options.issue || options.issueId || null;
 
 		// F4c: never link issue B onto a branch already bound to issue A.
@@ -1080,8 +989,8 @@ async function executePlan(featureName, options = {}) { // NOSONAR S3776
 			scope: scope.type,
 			issueBackend,
 			issueId: issue.issueId,
-			// Deprecated alias of issueId, retained for backward compatibility. It does
-			// NOT imply the Beads backend — on the kernel path it holds the kernel id.
+			// Deprecated alias of issueId, retained for output-shape compatibility.
+			// It never implied a Beads store and now always holds the kernel id.
 			beadsIssueId: issue.issueId,
 			branchName: branch.branchName,
 			linked: Boolean(explicitIssueId),
@@ -1151,7 +1060,6 @@ module.exports = {
 	},
 	readResearchDoc,
 	detectScope,
-	createBeadsIssue,
 	createKernelIssue,
 	createFeatureBranch,
 	extractDesignDecisions,

package/lib/commands/pr.js

@@ -33,7 +33,7 @@ const SUBCOMMANDS = {
   },
   merge: {
     module: merge,
-    summary: 'Opt-in conditional auto-merge, OFF by default (= forge merge --auto <pr>)',
+    summary: 'Opt-in guarded merge, OFF by default (= forge merge --auto <pr> --expect-head <sha> --issue <id>)',
   },
 };
 

package/lib/commands/preflight.js

@@ -103,7 +103,16 @@ function resolveChangeSet(exec = execFileSync, { runAll = false } = {}) {
   // Diff against the SAME base we just resolved. getChangedFiles() re-resolves
   // its own diff ref (and can fall back to a different default branch), so use
   // baseRef directly to keep the file list consistent with the resolved base.
-  return { resolved: true, baseRef, changedFiles: changedFilesForBase(exec, baseRef) };
+  const changedFiles = changedFilesForBase(exec, baseRef);
+  if (changedFiles == null) {
+    return {
+      resolved: false,
+      baseRef,
+      changedFiles: [],
+      reason: `git diff failed or timed out for ${baseRef}`,
+    };
+  }
+  return { resolved: true, baseRef, changedFiles };
 }
 
 /** Files changed between the merge-base of HEAD and `baseRef` and HEAD. */
@@ -111,7 +120,7 @@ function changedFilesForBase(exec, baseRef) {
   const mergeBase = gitTryOut(exec, ['merge-base', 'HEAD', baseRef]);
   const range = mergeBase ? `${mergeBase}...HEAD` : `${baseRef}...HEAD`;
   const out = gitTryOut(exec, ['diff', '--name-only', range]);
-  if (out == null) return [];
+  if (out == null) return null;
   return out.split(/\r?\n/).filter(Boolean);
 }
 

package/lib/commands/prime.js

@@ -2,12 +2,32 @@
 
 const {
   buildPrime,
+  collectPrimeLiveState,
   runOrientationCommand,
 } = require('../orientation');
 
+const DEPRECATION_NOTICE =
+  'forge prime is deprecated — run `forge status -v` for the same briefing.\n';
+
+// The single briefing renderer. `forge status -v` calls this so the full
+// session-entry briefing has exactly one implementation.
+// Async: the briefing leads with LIVE state (stage / claims / ready / gates / one
+// adoption nudge), which needs a best-effort (non-throwing) kernel read before the
+// synchronous build assembles it into the bounded orientation.
+async function renderBriefing(args, projectRoot) {
+  const liveState = await collectPrimeLiveState(projectRoot);
+  return runOrientationCommand(buildPrime, args, projectRoot, { liveState });
+}
+
 module.exports = {
   name: 'prime',
-  description: 'Emit session-entry bounded orientation for agents',
-  usage: 'Usage: forge prime [--budget N] [--json]',
-  handler: (args, _flags, projectRoot) => runOrientationCommand(buildPrime, args, projectRoot),
+  description: 'Deprecated alias for `forge status -v`: session-entry bounded orientation',
+  usage: 'Usage: forge prime [--budget N] [--json]  (deprecated — use `forge status -v`)',
+  // Session-start hooks in consumer repos call this and consume stdout as context,
+  // so the notice goes to stderr and stdout stays byte-identical to `status -v`.
+  handler: async (args, _flags, projectRoot, options = {}) => {
+    (options.stderr || process.stderr).write(DEPRECATION_NOTICE);
+    return renderBriefing(args, projectRoot);
+  },
+  renderBriefing,
 };

package/lib/commands/push.js

@@ -4,8 +4,8 @@ const { execFileSync, spawnSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
 const forgeToken = require('../../scripts/check-forge-token');
-const { startPrWatcherDetached } = require('../pr-monitor/watch-lifecycle');
-const { autoShepherdRailEnabled } = require('./ship');
+const { QUICK_LANE_ENV_VAR, QUICK_LANE_VALUE } = require('../../scripts/test');
+const { fireAndForget } = require('../pr-monitor/reconcile-executor');
 
 const isWindows = process.platform === 'win32';
 
@@ -113,54 +113,49 @@ async function autoFileBackingIssueForPush(projectRoot, execFn, deps = {}) {
 }
 
 /**
- * Resolve the OPEN PR number for the current branch via `gh pr view`. Returns
- * null when there is no PR, gh is unavailable, or anything errors (fail-open).
- * NEVER throws.
+ * Best-effort wake of the repository-wide singleton after a successful push.
+ * The shared trigger owns all containment and gate checks and never selects a
+ * per-PR watcher here.
  *
- * @param {function} execFn - execFileSync or mock
- * @returns {number|null}
+ * @param {object} params
+ * @returns {{ armed: boolean, reason?: string }}
  */
-function resolveOpenPrNumber(execFn) {
+function maybeTriggerShepherdAfterPush({
+	projectRoot,
+	fireAndForget: trigger = fireAndForget,
+}) {
 	try {
-		const out = execFn('gh', ['pr', 'view', '--json', 'number', '-q', '.number'], {
-			encoding: 'utf8', timeout: 15000, stdio: ['pipe', 'pipe', 'pipe'],
-		});
-		const n = Number.parseInt(String(out).trim(), 10);
-		return Number.isInteger(n) && n > 0 ? n : null;
-	} catch (_err) { /* intentional: no open PR / gh missing → arm nothing */ // NOSONAR S2486
-		return null;
+		trigger({ projectRoot });
+		return { armed: true };
+	} catch (err) {
+		return { armed: false, reason: err.message };
 	}
 }
 
 /**
- * Best-effort, NON-BLOCKING arm of the constant PR watcher after a successful
- * push, when an OPEN PR exists for the current branch. This closes the gap where
- * PRs not born from `forge ship` (gh pr create, the GitHub UI, an earlier push)
- * never got a watcher. Gated by the default-ON `rail.auto_shepherd`, idempotent
- * via the watch loop's own PID/journal lock, and reusing the same
- * `startPrWatcherDetached` as ship. MUST NEVER throw into or fail the push: a
- * disabled rail, no PR, a gh error, or a spawn error all degrade to
- * `{ armed: false }`.
+ * Build the environment for the spawned `git push`, declaring the push lane.
  *
- * @param {object} params
- * @returns {{ armed: boolean, reason?: string, prNumber?: number }}
+ * `--quick` skips the test step push.js controls, but the `git push` it spawns
+ * still fires the lefthook pre-push hook, whose tests job runs scripts/test.js —
+ * so --quick was quick only up to the push. This declares the lane to that hook
+ * so the quick lane is lint-only end to end.
+ *
+ * The declaration is set on the child env only, and is explicitly REMOVED for a
+ * full push so an inherited value from an outer shell can never silently drop
+ * the tests from a `forge push`.
+ *
+ * @param {boolean} quickMode - Whether this is a --quick push
+ * @param {NodeJS.ProcessEnv} [baseEnv=process.env] - Environment to derive from
+ * @returns {NodeJS.ProcessEnv} Environment for the git push child process
  */
-function maybeArmWatcherAfterPush({
-	projectRoot,
-	execFn,
-	startWatcher = startPrWatcherDetached,
-	railEnabled = autoShepherdRailEnabled,
-	prLookup = resolveOpenPrNumber,
-}) {
-	try {
-		if (!railEnabled(projectRoot)) return { armed: false, reason: 'rail.auto_shepherd disabled' };
-		const prNumber = prLookup(execFn);
-		if (!prNumber) return { armed: false, reason: 'no-open-pr' };
-		const res = startWatcher({ prNumber, cwd: projectRoot });
-		return { armed: !!(res && res.started), reason: res && res.reason, prNumber };
-	} catch (err) {
-		return { armed: false, reason: err.message };
+function buildPushEnv(quickMode, baseEnv = process.env) {
+	const env = { ...baseEnv };
+	if (quickMode) {
+		env[QUICK_LANE_ENV_VAR] = QUICK_LANE_VALUE;
+	} else {
+		delete env[QUICK_LANE_ENV_VAR];
 	}
+	return env;
 }
 
 /**
@@ -288,7 +283,7 @@ module.exports = {
 		// Step 5: git push with passthrough args
 		const gitArgs = args.filter(a => a !== '--quick');
 		try {
-			execFn('git', ['push', ...gitArgs], { stdio: 'inherit' });
+			execFn('git', ['push', ...gitArgs], { stdio: 'inherit', env: buildPushEnv(quickMode) });
 		} catch (_pushErr) { // NOSONAR S2486
 			log('git push failed.');
 			return {
@@ -300,15 +295,10 @@ module.exports = {
 			};
 		}
 
-		// Arm the constant PR watcher for this branch's open PR (best-effort,
-		// gated by rail.auto_shepherd, never fails the push). Covers PRs not born
-		// from `forge ship`.
-		maybeArmWatcherAfterPush({
+		// Wake the repository-wide singleton after a successful push.
+		maybeTriggerShepherdAfterPush({
 			projectRoot,
-			execFn,
-			startWatcher: deps?.startWatcher,
-			railEnabled: deps?.railEnabled,
-			prLookup: deps?.prLookup,
+			fireAndForget: deps?.fireAndForget,
 		});
 
 		return {
@@ -323,7 +313,7 @@ module.exports = {
 	// Exposed for unit tests; not part of the CLI surface.
 	_internal: {
 		autoFileBackingIssueForPush,
-		maybeArmWatcherAfterPush,
-		resolveOpenPrNumber,
+		buildPushEnv,
+		maybeTriggerShepherdAfterPush,
 	},
 };

package/lib/commands/recall.js

@@ -3,8 +3,11 @@
 const memoryRouter = require('../memory/router');
 const { stripGlobalFlags } = require('../global-flags');
 const { fenceUntrusted } = require('../untrusted-content');
+const { applyBudget, buildSection, estimateTokens } = require('../orientation');
+const { memoryTrustStatus } = require('../memory-recall');
 
 const usage = 'Usage: forge recall [query] [--kind <type>] [--limit N] [--all] [--json]';
+const RECALL_CONTENT_BUDGET = 1100;
 
 // Reserved tag prefix that `remember --kind` writes (kernel issue 8cc1db4d). A `--kind`
 // filter keeps only notes carrying this tag; the prefix is stripped when surfacing the
@@ -79,21 +82,28 @@ function withType(entry) {
 
 function formatEntry(entry) {
   const date = entry.timestamp ? entry.timestamp.slice(0, 10) : '';
-  const prefix = date ? `${date}  ` : '';
+  const trust = memoryTrustStatus({
+    tags: entry.tags,
+    sourceAgent: entry.sourceAgent,
+    value: entry.machine ? {} : entry.note,
+  });
+  const sourceAgent = entry.sourceAgent || 'unknown';
+  const label = `[source=${sourceAgent} trust=${trust} updated=${date || 'unknown'}] `;
   // The reserved `type:` tag renders as a leading `(kind)` marker, not as a raw tag, so the
   // displayed tags stay the user's own labels.
   const type = typeOf(entry);
-  const userTags = (entry.tags || []).filter(t => !t.startsWith(TYPE_TAG_PREFIX));
+  const userTags = (entry.tags || []).filter(
+    t => !t.startsWith(TYPE_TAG_PREFIX) && !t.startsWith('trust:')
+  );
   const tagSuffix = userTags.length > 0 ? ` [${userTags.join(', ')}]` : '';
   const typeMarker = type ? `(${type}) ` : '';
   // Machine/insights records are LABELED with their source so they are never mistaken for a
   // plain human note; human `remember` notes render clean.
   const marker = entry.machine && entry.sourceAgent ? `(${entry.sourceAgent}) ` : '';
-  // Stored note text is UNTRUSTED (a planted memory could carry injected directives),
-  // so the human/agent-facing render is provenance-fenced. The `--json` path above
-  // keeps the raw note so programmatic consumers/parsers are unaffected.
-  const note = fenceUntrusted(entry.note, { source: 'memory' });
-  return `- ${prefix}${marker}${typeMarker}${note}${tagSuffix}`;
+  // Stored note text is untrusted. Fence it after budgeting so a truncation cannot
+  // sever the close marker; the `--json` path above keeps the raw note unchanged.
+  const note = String(entry.note == null ? '' : entry.note);
+  return `- ${label}${marker}${typeMarker}${note}${tagSuffix}`;
 }
 
 async function handler(args, flags, projectRoot) {
@@ -137,23 +147,57 @@ async function handler(args, flags, projectRoot) {
     return { success: true, output: reason };
   }
 
+  const sections = notes
+    .map((entry, index) => {
+      const content = formatEntry(entry);
+      if (estimateTokens(content) > RECALL_CONTENT_BUDGET) return null;
+      const trust = memoryTrustStatus({
+        tags: entry.tags,
+        sourceAgent: entry.sourceAgent,
+        value: entry.machine ? {} : entry.note,
+      });
+      return buildSection({
+        id: `recall_${index}`,
+        title: '',
+        content,
+        priority: index,
+        preserve: false,
+        data: { trust },
+      });
+    })
+    .filter(Boolean);
+  const budgeted = applyBudget(sections, RECALL_CONTENT_BUDGET).sections
+    .filter(section => section.content);
+  for (const section of budgeted) {
+    section.content = fenceUntrusted(section.content, { source: 'memory' });
+  }
+  const rendered = budgeted.length;
   const noun = scope === 'all' && !query ? 'stored memory record(s)' : 'remembered note(s)';
   let header;
   if (query) {
     // BM25 returns at most `limit`; when full, signal it is the TOP-N, not the whole set.
-    header = capped
-      ? `Top ${notes.length} note(s) matching "${query}" (raise --limit for more):`
-      : `${notes.length} note(s) matching "${query}":`;
-  } else if (capped) {
-    // Never a bare full dump: show the newest N and the true total.
-    header = `Showing ${notes.length} of ${total} ${noun} (newest first):`;
+    header = capped || rendered < notes.length
+      ? `Top ${rendered} note(s) matching "${query}" (raise --limit for more):`
+      : `${rendered} note(s) matching "${query}":`;
+  } else if (capped || rendered < notes.length) {
+    // Never a bare full dump: show the rendered count and the true total.
+    header = `Showing ${rendered} of ${total} ${noun} (newest first):`;
   } else {
-    header = `${total} ${noun}:`;
+    header = `${rendered} ${noun}:`;
   }
-  const lines = notes.map(formatEntry);
+  const confirmed = budgeted.filter(section => section.data.trust === 'confirmed');
+  const suggested = budgeted.filter(section => section.data.trust === 'suggested');
+  const groups = [
+    confirmed.length ? ['Confirmed memory', confirmed] : null,
+    suggested.length ? ['Suggested memory — verify before relying', suggested] : null,
+  ].filter(Boolean);
+  const body = groups.flatMap(([title, entries]) => [
+    title,
+    ...entries.map(entry => entry.content),
+  ]);
   return {
     success: true,
-    output: [header, ...lines].join('\n'),
+    output: [header, ...body].join('\n'),
   };
 }
 

package/lib/commands/recap.js

@@ -46,7 +46,12 @@ async function handler(args, _flags, projectRoot, opts = {}) {
   }
 
   const budget = readOption(args, '--budget', undefined);
-  const recap = buildIssueRecap(projectRoot, issueId, { budgetTokens: budget });
+  // `runIssueOperation` is the injectable kernel-read seam (Slice C2) — the same
+  // pass-through opts already carry for the grounding write below.
+  const recap = await buildIssueRecap(projectRoot, issueId, {
+    budgetTokens: budget,
+    runIssueOperation: opts.runIssueOperation,
+  });
 
   // Grounding (gate.read_first): a successful recap IS the load-the-doc action,
   // so append a `context.loaded` event that unblocks a later `forge claim <id>`.

package/lib/commands/release.js

@@ -8,13 +8,13 @@ const {
 } = require('../release-readiness');
 const { runIssueOperation: defaultRunIssueOperation } = require('../forge-issues');
 const { normalizeArgs, normalizeIssueResult, withResolvedIssueBackend } = require('./_issue');
+const { generateNpmPublishWorkflow } = require('../npm-publish-workflow');
 
 // `forge release <id>` releases a claimed issue; `forge release check` runs the
 // release-readiness gate. The two share the top-level verb, so this command
 // dispatches `check` to the gate and routes everything else through the shared
-// issue dispatch (resolve backend → runIssueOperation('release') → normalize). The
-// Beads backend has no release op and returns the Kernel-only contract error.
-const usage = 'Usage: forge release <id>  |  forge release check --target 0.1.0 [--json]  |  forge release regen-audit';
+// issue dispatch (resolve backend → runIssueOperation('release') → normalize).
+const usage = 'Usage: forge release <id>  |  forge release check --target 0.1.0 [--json]  |  forge release regen-audit  |  forge release generate-npm-workflow';
 
 async function runReleaseIssue(args, projectRoot, opts = {}) {
   const resolved = withResolvedIssueBackend(projectRoot, opts);
@@ -56,7 +56,21 @@ function parseReleaseArgs(args = []) {
 }
 
 async function handler(args, _flags, projectRoot, opts = {}) {
-  const parsed = parseReleaseArgs(args);
+	const parsed = parseReleaseArgs(args);
+
+	if (parsed.subcommand === 'generate-npm-workflow') {
+		const generated = await generateNpmPublishWorkflow(projectRoot, {
+			env: opts.env,
+			kernelDeps: opts.kernelDeps,
+		});
+		return generated.success
+			? {
+				success: true,
+				generated,
+				output: `Generated ${generated.path} (${generated.contentHash}).\n`,
+			}
+			: generated;
+	}
 
   if (parsed.subcommand === 'regen-audit') {
     // forge release regen-audit — rewrite the D20 kill-list from a live re-scan.

package/lib/commands/serve.js

@@ -240,7 +240,7 @@ async function routeMutation(verb, args, projectRoot, deps = {}) {
 function defaultGenerate(projectRoot, dashboardDir) {
   return new Promise((resolve, reject) => {
     const script = path.join(dashboardDir, 'generate-snapshot.mjs');
-    const child = spawn(process.execPath, [script], { cwd: projectRoot, stdio: 'ignore' });
+    const child = spawn(process.execPath, [script], { cwd: projectRoot, stdio: 'ignore', windowsHide: true });
     const timer = setTimeout(() => { child.kill(); reject(new Error('snapshot generation timed out')); }, GEN_TIMEOUT_MS);
     child.on('error', (err) => { clearTimeout(timer); reject(err); });
     child.on('exit', (code) => {
@@ -441,7 +441,10 @@ function browserOpener() {
 function openBrowser(url) {
   try {
     const { file, args } = browserOpener();
-    const child = spawn(file, [...args, url], { detached: true, stdio: 'ignore' });
+    // windowsHide keeps this detached opener from flashing a console window on
+    // Windows (Node defaults windowsHide to false); background/detached spawns
+    // must stay silent (issue 931e7924).
+    const child = spawn(file, [...args, url], { detached: true, stdio: 'ignore', windowsHide: true });
     // spawn() failures (e.g. the opener binary is missing) surface ASYNChronously
     // as an 'error' event, NOT via the try/catch — an unhandled one would crash
     // `forge serve`. Opening a browser is best-effort; swallow it (URL is printed).