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

package/lib/commands/_resolve-command-opts.js

@@ -5,15 +5,17 @@
  * handler (the 4th arg). For issue/alias commands this:
  *
  *   1. Strips the selector tokens (`--kernel`, `--issue-backend <val>`) from the
- *      args BEFORE they reach the handler / bd. This is load-bearing: bin
- *      parseFlags() early-returns for issue passthrough commands, so these tokens
- *      otherwise flow untouched into the handler and (beads path) into bd, which
- *      rejects the unknown flag — and the positional `kernel`/`beads` value would
- *      be mistaken for an issue id.
+ *      args BEFORE they reach the handler. This is load-bearing: bin parseFlags()
+ *      early-returns for issue passthrough commands, so these tokens otherwise flow
+ *      untouched into the handler and the positional `kernel` value would be
+ *      mistaken for an issue id.
  *   2. Resolves the backend (flag > env > config > default) via the backend
  *      authority module (lib/issue-backend.js). The CLI flag tokens are mapped to
  *      that module's `deps.issueBackend` signal; env/config/default precedence is
- *      applied by the resolver itself.
+ *      applied by the resolver itself. `kernel` is the only accepted value — a
+ *      retired backend named on the FLAG is a hard error (the user typed it in this
+ *      invocation, so silently ignoring it would run the wrong store), while the
+ *      same value in env/config only warns and falls back.
  *   3. When kernel, assembles the kernel deps (driver + flag) via the CLI broker
  *      factory so createKernelIssueBackend has a real driver (B1).
  *
@@ -24,7 +26,7 @@
  * @module commands/resolve-command-opts
  */
 
-const { resolveIssueBackend } = require('../issue-backend');
+const { resolveIssueBackend, removedBackendHint } = require('../issue-backend');
 const {
   buildMigratedKernelIssueDeps: defaultBuildKernelIssueDeps,
 } = require('../kernel/cli-broker-factory');
@@ -45,14 +47,11 @@ const ISSUE_COMMANDS = new Set([
   'stale',
   'orphans',
   'lint',
-  // Epic grouping read — must be kernel-routed (its issue.children rollup has no
-  // verified Beads equivalent), so it belongs in ISSUE_COMMANDS like the rest.
+  // Epic grouping read (issue.children rollup).
   'children',
-  // Lease-ownership verification — a kernel-only read (leases live in the Kernel),
-  // so it is kernel-routed like the rest of the issue surface.
+  // Lease-ownership verification (leases live in the Kernel).
   'owns',
-  // Active-lease listing — a kernel-only read (leases live in the Kernel), so it
-  // is kernel-routed like the rest of the issue surface.
+  // Active-lease listing (leases live in the Kernel).
   'claims',
   'search',
   'stats',
@@ -101,7 +100,7 @@ function stripSelectorTokens(rawArgs = []) {
         flags.issueBackend = next;
         i += 1;
       } else {
-        throw new Error(`${ISSUE_BACKEND_FLAG} requires a value: kernel or beads.`);
+        throw new Error(`${ISSUE_BACKEND_FLAG} requires a value: kernel.`);
       }
       continue;
     }
@@ -109,7 +108,7 @@ function stripSelectorTokens(rawArgs = []) {
       // Equals form: reject an empty value (`--issue-backend=`) for the same reason.
       const value = token.slice(ISSUE_BACKEND_FLAG.length + 1).trim();
       if (!value) {
-        throw new Error(`${ISSUE_BACKEND_FLAG} requires a value: kernel or beads.`);
+        throw new Error(`${ISSUE_BACKEND_FLAG} requires a value: kernel.`);
       }
       flags.issueBackend = value;
       continue;
@@ -122,12 +121,14 @@ function stripSelectorTokens(rawArgs = []) {
 /**
  * Reduce the stripped selector flags to a single explicit backend value (or null
  * when no flag selects one), honoring `--kernel` / `--issue-backend` equivalence
- * and rejecting a mutually-exclusive conflict. Returned values are NOT validated
- * here — the backend authority module normalizes/warns on unknown values.
+ * and rejecting a mutually-exclusive conflict. A RETIRED backend value is rejected
+ * here with the migrate pointer; any other value is NOT validated here — the backend
+ * authority module normalizes/warns on unknown values.
  *
  * @param {{ kernel?: boolean, issueBackend?: string }} flags
  * @returns {string|null}
- * @throws {Error} when --kernel and --issue-backend select different backends.
+ * @throws {Error} when --kernel and --issue-backend select different backends, or
+ *   when --issue-backend names a removed backend.
  */
 function resolveFlagBackend(flags = {}) {
   const fromBackend = typeof flags.issueBackend === 'string' && flags.issueBackend.trim()
@@ -142,6 +143,19 @@ function resolveFlagBackend(flags = {}) {
     );
   }
 
+  // Hard error (not the resolver's warn+fallback) because the value was typed into
+  // THIS invocation: silently running the kernel after the user explicitly asked for
+  // a different store is the kind of surprise that loses writes.
+  if (fromBackend) {
+    const removedHint = removedBackendHint(fromBackend);
+    if (removedHint) {
+      throw new Error(
+        `${ISSUE_BACKEND_FLAG} ${fromBackend} is no longer supported: ${removedHint}. `
+        + `Only '${KERNEL}' is accepted.`,
+      );
+    }
+  }
+
   return fromKernel || fromBackend || null;
 }
 
@@ -188,22 +202,15 @@ async function resolveCommandOpts(command, rawArgs = [], deps = {}) {
 
   const { args, flags } = stripSelectorTokens(rawArgs);
   const flagBackend = resolveFlagBackend(flags);
-  const issueBackend = resolveIssueBackend({
+  // Still routed through the authority module (rather than hardcoding 'kernel') so a
+  // retired/unknown env or config value produces its warning exactly once, here, on
+  // the way to the kernel fallback.
+  resolveIssueBackend({
     deps: flagBackend ? { issueBackend: flagBackend } : {},
     env,
     projectRoot: deps.projectRoot,
   });
 
-  if (issueBackend !== KERNEL) {
-    return {
-      commandOpts: {
-        issueBackend,
-        useKernelBroker: false,
-      },
-      args,
-    };
-  }
-
   // Kernel backend: assemble the driver (B1) + migrated broker (B2). The factory
   // builder constructs the driver, builds the broker, and runs initialize().
   const kernelDeps = await buildKernelIssueDeps({

package/lib/commands/claim.js

@@ -3,10 +3,8 @@
 const { runIssueSubcommand } = require('./_issue');
 
 // `forge claim <id>` claims an issue through the SHARED issue dispatch
-// (runIssueSubcommand): backend resolution (Kernel via --kernel /
-// --issue-backend kernel / FORGE_ISSUE_BACKEND=kernel, Beads otherwise; the
-// Beads backend translates claim to `update <id> --claim`), contract
-// normalization, AND the check-after-write verification loop
+// (runIssueSubcommand): backend resolution (the Kernel is the only backend),
+// contract normalization, AND the check-after-write verification loop
 // (gate.issue_verify). This command previously inlined its own copy of the
 // dispatch, which silently BYPASSED the boundary verify — the exact surface
 // where the d71a824b phantom-claim replay lied to a losing agent — so it now

package/lib/commands/hooks.js

@@ -27,16 +27,81 @@ const {
   renderGlobalHookBlock,
   installGlobalHooks,
 } = require('../hook-global-installer');
+const fs = require('node:fs');
+const path = require('node:path');
 const { sessionStartCapability, userPromptSubmitCapability, sessionEndCapability } = require('../hook-renderer');
 const { collectDigestData, buildMemoryDigest, defaultFetchIssues, defaultFetchNotes } = require('../memory-digest');
 const { collectInbox, buildInboxNudge } = require('../inbox');
 const { collectDigest } = require('../pr-monitor/digest');
+const { loadDispatchText } = require('../using-forge');
+const projectMemory = require('../project-memory');
+const { parseHookInput, selectInjection, DEFAULT_TOKEN_BUDGET, DEFAULT_SCORE_FLOOR } = require('../memory-recall');
+const { fenceUntrusted } = require('../untrusted-content');
+const { getResolvedRuntimeGraph } = require('../core/runtime-graph');
+
+// Default-ON rail; `forge gate disable rail.memory_recall` turns tier-2 off. Mirrors
+// autoShepherdRailEnabled (lib/commands/ship.js): absent id = enabled, fail-open to true.
+const MEMORY_RECALL_RAIL = 'rail.memory_recall';
+// bm25 candidate pool to rank/floor down from. Wider than what we inject so the floor +
+// dedupe have room (mirrors the research "widen before ranking" guidance).
+const MEMORY_RECALL_CANDIDATES = 25;
+// Cross-turn dedupe memory: how many recently-injected keys to remember per session.
+const SEEN_KEYS_CAP = 40;
+
+function memoryRecallRailEnabled(projectRoot, resolveGraph = getResolvedRuntimeGraph) {
+  try {
+    const graph = resolveGraph({ projectRoot });
+    const rail = [...(graph.rails || []), ...(graph.gates || [])].find(entry => entry.id === MEMORY_RECALL_RAIL);
+    return !(rail?.enabled === false);
+  } catch {
+    return true;
+  }
+}
+
+// Read the hook's stdin payload (Claude delivers UserPromptSubmit JSON on fd 0). Never
+// throws — no stdin / a closed fd yields '' so the hook fails open.
+function readHookStdin() {
+  try {
+    return fs.readFileSync(0, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function seenPath(projectRoot, sessionId) {
+  const safe = String(sessionId || 'nosession').replace(/[^a-zA-Z0-9_-]/g, '_');
+  return path.join(projectRoot, '.forge', 'memory-recall', `${safe}.json`);
+}
+
+// Keys injected on recent turns of THIS session (cross-turn dedupe). Best-effort: any read
+// error yields [] so a first turn or a corrupt file simply injects without exclusion.
+function loadSeenKeys(projectRoot, sessionId) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(seenPath(projectRoot, sessionId), 'utf8'));
+    return Array.isArray(parsed) ? parsed.filter(k => typeof k === 'string') : [];
+  } catch {
+    return [];
+  }
+}
+
+// Append the just-injected keys to the session's seen-list (newest last, capped). Best-effort.
+function saveSeenKeys(projectRoot, sessionId, keys) {
+  try {
+    const merged = [...loadSeenKeys(projectRoot, sessionId), ...keys].slice(-SEEN_KEYS_CAP);
+    const file = seenPath(projectRoot, sessionId);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(merged), 'utf8');
+  } catch {
+    // Dedupe is a nicety, not a correctness gate — a failed write never breaks the prompt.
+  }
+}
 
 function usage() {
   return 'Usage: forge hooks install --global [--harness codex|hermes|all] [--dry-run]\n'
     + '       forge hooks session-start --harness <claude> (machine-facing; emits SessionStart context)\n'
     + '       forge hooks inbox-pickup --harness <claude> (machine-facing; emits UserPromptSubmit context)\n'
     + '       forge hooks shepherd-events --harness <claude> (machine-facing; emits UserPromptSubmit PR-monitor deltas)\n'
+    + '       forge hooks memory-recall --harness <claude> (machine-facing; emits UserPromptSubmit query-relevant memory)\n'
     + '       forge hooks capture --harness <claude> --trigger <precompact|stop> (machine-facing; captures a session summary on exit)';
 }
 
@@ -115,17 +180,35 @@ function formatSessionStart(harness, text) {
  * @returns {Promise<{ success: boolean, output: string }>}
  */
 async function handleSessionStart(rest, projectRoot, opts = {}) {
+  const harness = parseHarness(rest);
+  if (!sessionStartCapability(harness).rendered) return { success: true, output: '' };
+
+  // NOTE: the autonomous-shepherd session-start trigger is deferred to W-S4c along with the
+  // per-command dispatch trigger — both need a firing-policy + containment design (a naive
+  // trigger spawns a session-outliving daemon that breaks test isolation).
+
+  // The using-forge dispatch bootstrap is injected FIRST so Forge skills auto-trigger from turn
+  // one (the Superpowers mechanism): a reasoning-driven system, not just harness description
+  // matching. It is a deterministic file read that survives a kernel outage. The memory digest
+  // (remembered notes + top open issues) is appended when present. Either alone is enough to
+  // inject; a total blank yields '' (the harness injects nothing). FAIL-OPEN throughout.
+  let dispatch = '';
+  try {
+    // No projectRoot: the dispatch skill is read from the Forge PACKAGE's canonical skills/
+    // (a set-up consumer project has no root skills/, only generated mirrors).
+    dispatch = (opts.loadDispatchText || loadDispatchText)() || '';
+  } catch { /* keep '' — a missing dispatch skill must not break session start */ }
+
+  let digestText = '';
   try {
-    const harness = parseHarness(rest);
-    if (!sessionStartCapability(harness).rendered) return { success: true, output: '' };
     const data = await collectDigestData(projectRoot, opts);
     const digest = buildMemoryDigest(data, opts);
-    if (digest.empty) return { success: true, output: '' };
-    return { success: true, output: formatSessionStart(harness, digest.text) };
-  } catch {
-    // Fail-open: a context hook must never break a session.
-    return { success: true, output: '' };
-  }
+    if (!digest.empty) digestText = digest.text;
+  } catch { /* fail-open: a kernel outage must not suppress the dispatch bootstrap */ }
+
+  const combined = [dispatch, digestText].filter(Boolean).join('\n\n');
+  if (!combined) return { success: true, output: '' };
+  return { success: true, output: formatSessionStart(harness, combined) };
 }
 
 /** Wrap a digest into a harness-native UserPromptSubmit payload, or '' when unsupported. */
@@ -205,6 +288,69 @@ function handleShepherdEvents(rest, projectRoot, opts = {}) {
   }
 }
 
+/**
+ * `forge hooks memory-recall --harness <h>` — the QUERY-RELEVANT memory tier (tier-2). On each
+ * prompt it reads the submitted prompt from the hook's stdin, ranks stored memories by BM25
+ * relevance to it (NOT recency — that is the SessionStart digest's job), applies a relevance
+ * floor + anaphora guard + cross-turn dedupe + a hard token budget, and emits the survivors as
+ * harness-native UserPromptSubmit context. Complements the always-on recency digest: this one
+ * answers "what memory is relevant to THIS turn".
+ *
+ * Compliance + safety (verified against the Claude Code hooks contract, kernel issue 781f6f65):
+ *   - It READS its own hook stdin (the supported input channel) — it does NOT inject into a
+ *     running session's stdin and never drives the agent (Anthropic Usage Policy).
+ *   - additionalContext APPENDS to history every prompt, so the injection is tiny and gated:
+ *     below the relevance floor, or on a low-signal (anaphora) prompt, it injects NOTHING.
+ *   - Injected memory bodies are UNTRUSTED (a planted note could carry directives), so each is
+ *     provenance-fenced.
+ *   - UserPromptSubmit has a 30s timeout and blocks the prompt; the read is local BM25 over
+ *     SQLite (sub-ms) and FAIL-OPEN — any error, a disabled rail, an unsupported harness, or
+ *     nothing relevant yields '' and the prompt proceeds untouched. NEVER throws.
+ *   - Kill-switch: `forge gate disable rail.memory_recall`.
+ *
+ * @param {string[]} rest - args after the `memory-recall` action.
+ * @param {string} projectRoot
+ * @param {object} [opts] - injectable seams for tests: { railEnabled, readInput, search,
+ *   loadSeen, saveSeen, scoreFloor, tokenBudget }.
+ * @returns {{ success: boolean, output: string }}
+ */
+function handleMemoryRecall(rest, projectRoot, opts = {}) {
+  try {
+    const harness = parseHarness(rest);
+    if (!userPromptSubmitCapability(harness).rendered) return { success: true, output: '' };
+
+    const railEnabled = opts.railEnabled || memoryRecallRailEnabled;
+    if (!railEnabled(projectRoot)) return { success: true, output: '' };
+
+    const readInput = opts.readInput || readHookStdin;
+    const { prompt, sessionId } = parseHookInput(readInput());
+    if (!prompt) return { success: true, output: '' };
+
+    const search = opts.search
+      || ((root, query, limit) => projectMemory.searchRankedScored(root, query, limit));
+    const loadSeen = opts.loadSeen || loadSeenKeys;
+    const saveSeen = opts.saveSeen || saveSeenKeys;
+
+    const hits = search(projectRoot, prompt, MEMORY_RECALL_CANDIDATES) || [];
+    const excludeKeys = loadSeen(projectRoot, sessionId) || [];
+    const { lines, injectedKeys } = selectInjection({
+      query: prompt,
+      hits,
+      scoreFloor: typeof opts.scoreFloor === 'number' ? opts.scoreFloor : DEFAULT_SCORE_FLOOR,
+      tokenBudget: opts.tokenBudget || DEFAULT_TOKEN_BUDGET,
+      excludeKeys,
+    });
+    if (!lines.length) return { success: true, output: '' };
+
+    saveSeen(projectRoot, sessionId, injectedKeys);
+    const fenced = lines.map(line => fenceUntrusted(line, { source: 'memory' })).join('\n');
+    return { success: true, output: formatUserPromptSubmit(harness, fenced) };
+  } catch {
+    // Fail-open: a context hook must never break a prompt.
+    return { success: true, output: '' };
+  }
+}
+
 /**
  * `forge hooks capture --harness <h> --trigger <precompact|stop>` — the CAPTURE-on-exit hook.
  * PreCompact (before context compaction) and Stop (turn end) fire it; it snapshots a bounded
@@ -356,6 +502,7 @@ async function handler(args, flags = {}, projectRoot, opts = {}) {
   if (action === 'session-start') return handleSessionStart(args.slice(1), projectRoot, opts);
   if (action === 'inbox-pickup') return handleInboxPickup(args.slice(1), projectRoot, opts);
   if (action === 'shepherd-events') return handleShepherdEvents(args.slice(1), projectRoot, opts);
+  if (action === 'memory-recall') return handleMemoryRecall(args.slice(1), projectRoot, opts);
   if (action === 'capture') return handleCapture(args.slice(1), projectRoot, opts);
   if (action === 'install') return handleInstall(args, flags, opts);
   return {

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/prime.js

@@ -2,6 +2,7 @@
 
 const {
   buildPrime,
+  collectPrimeLiveState,
   runOrientationCommand,
 } = require('../orientation');
 
@@ -9,5 +10,11 @@ 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),
+  // Async: prime 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. All existing prime output/flags are unchanged.
+  handler: async (args, _flags, projectRoot) => {
+    const liveState = await collectPrimeLiveState(projectRoot);
+    return runOrientationCommand(buildPrime, args, projectRoot, { liveState });
+  },
 };

package/lib/commands/release.js

@@ -12,8 +12,7 @@ const { normalizeArgs, normalizeIssueResult, withResolvedIssueBackend } = requir
 // `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.
+// 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';
 
 async function runReleaseIssue(args, projectRoot, opts = {}) {

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).

package/lib/commands/setup.js

@@ -188,7 +188,6 @@ const WORKFLOW_RUNTIME_ASSETS = Object.freeze([
   'scripts/forge-team/index.sh',
   'scripts/forge-team/lib/agent-prompt.sh',
   'scripts/forge-team/lib/claim.sh',
-  'scripts/forge-team/lib/dashboard.sh',
   'scripts/forge-team/lib/epic.sh',
   'scripts/forge-team/lib/hooks.sh',
   'scripts/forge-team/lib/identity.sh',