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

package/lib/commands/recall.js

@@ -4,22 +4,34 @@ const memoryRouter = require('../memory/router');
 const { stripGlobalFlags } = require('../global-flags');
 const { fenceUntrusted } = require('../untrusted-content');
 
-const usage = 'Usage: forge recall [query] [--limit N] [--all] [--json]';
+const usage = 'Usage: forge recall [query] [--kind <type>] [--limit N] [--all] [--json]';
+
+// 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
+// derived `type` field so a note's user tags stay clean. The filter FLAG is `--kind` (NOT
+// `--type`): `--type` is a reserved GLOBAL flag hard-validated to workflow classifications.
+const TYPE_TAG_PREFIX = 'type:';
+
+// When a `--kind` filter is active the tag filter runs in the command layer (the store is
+// not reimplemented), so scan a generous window of recent notes before filtering rather than
+// the small default page — otherwise the type match could fall outside the default limit.
+const TYPE_FILTER_SCAN = 1000;
 
 /**
- * Separate the optional positional query from `--limit N` and `--json`.
- * Global flags (e.g. `-p <dir>`, `--all`) are stripped first so they never
- * corrupt the search query (kernel issue c1e090ff). `--all` is a GLOBAL boolean
- * flag, so the handler reads it from its `flags` argument (or the raw args on a
- * direct call) — not from this parsed query.
+ * Separate the optional positional query from `--kind <type>`, `--limit N`, and `--json`.
+ * Global flags (e.g. `-p <dir>`, `--all`) are stripped first so they never corrupt the
+ * search query (kernel issue c1e090ff). `--all` is a GLOBAL boolean flag, so the handler
+ * reads it from its `flags` argument (or the raw args on a direct call) — not from here.
+ * `--kind` is NOT a global flag, so it survives the strip and is parsed here.
  *
  * @param {string[]} rawArgs - Raw command arguments.
- * @returns {{ query: string, limit: (number|undefined), json: boolean }}
+ * @returns {{ query: string, limit: (number|undefined), type: (string|undefined), json: boolean }}
  */
 function parseArgs(rawArgs) {
   const args = stripGlobalFlags(rawArgs);
   const words = [];
   let limit;
+  let type;
   let json = false;
 
   for (let index = 0; index < args.length; index += 1) {
@@ -37,18 +49,43 @@ function parseArgs(rawArgs) {
       if (Number.isInteger(value) && value > 0) {
         limit = value;
       }
+    } else if (arg === '--kind') {
+      const value = args[index + 1];
+      if (value && !value.startsWith('--')) {
+        type = value.trim();
+        index += 1;
+      }
+    } else if (arg.startsWith('--kind=')) {
+      type = arg.slice('--kind='.length).trim();
     } else {
       words.push(arg);
     }
   }
 
-  return { query: words.join(' ').trim(), limit, json };
+  return { query: words.join(' ').trim(), limit, type, json };
+}
+
+// Derive a note's `type` from its reserved `type:` tag (undefined when untyped), so any
+// surface — JSON and text — can show and filter by kind without exposing the tag encoding.
+function typeOf(entry) {
+  const tag = (entry.tags || []).find(t => t.startsWith(TYPE_TAG_PREFIX));
+  return tag ? tag.slice(TYPE_TAG_PREFIX.length) : undefined;
+}
+
+function withType(entry) {
+  const type = typeOf(entry);
+  return type ? { ...entry, type } : entry;
 }
 
 function formatEntry(entry) {
   const date = entry.timestamp ? entry.timestamp.slice(0, 10) : '';
   const prefix = date ? `${date}  ` : '';
-  const tagSuffix = entry.tags.length > 0 ? ` [${entry.tags.join(', ')}]` : '';
+  // 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 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}) ` : '';
@@ -56,16 +93,33 @@ function formatEntry(entry) {
   // 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}${note}${tagSuffix}`;
+  return `- ${prefix}${marker}${typeMarker}${note}${tagSuffix}`;
 }
 
 async function handler(args, flags, projectRoot) {
-  const { query, limit, json } = parseArgs(args);
+  const { query, limit, type, json } = parseArgs(args);
   // `--all` is a GLOBAL boolean flag: in production bin/forge.js strips it from
   // args and sets flags.all; on a direct handler call it may still be in args.
   const all = Boolean(flags && flags.all) || args.includes('--all');
 
-  const { notes, total, capped, scope } = memoryRouter.recall(projectRoot, { query, limit, all });
+  // A `--type` filter scans a generous recent window, then keeps only matching notes — the
+  // read stays entirely in the existing store (no schema change). `--limit` is re-applied
+  // AFTER filtering so it caps the typed result set, not the pre-filter scan.
+  const recallLimit = type ? Math.max(limit ?? 0, TYPE_FILTER_SCAN) : limit;
+  const result = memoryRouter.recall(projectRoot, { query, limit: recallLimit, all });
+  let notes = result.notes.map(withType);
+  let { total, capped } = result;
+  const { scope } = result;
+  if (type) {
+    notes = notes.filter(entry => entry.type === type);
+    total = notes.length;
+    if (limit && notes.length > limit) {
+      notes = notes.slice(0, limit);
+      capped = true;
+    } else {
+      capped = false;
+    }
+  }
 
   if (json) {
     // Object (not a bare array) so programmatic consumers see the total and whether the
@@ -108,6 +162,7 @@ module.exports = {
   description: 'Retrieve project-memory notes from the kernel-backed memory store',
   usage,
   flags: {
+    '--kind': 'Filter to notes of a type (decision|bugfix|gotcha|...); --type is reserved',
     '--limit': 'Cap the number of notes returned',
     '--all': 'Include machine/insights records in the no-query listing (query already searches all)',
     '--json': 'Emit machine-readable JSON output',

package/lib/commands/recap.js

@@ -4,6 +4,7 @@ const {
   buildIssueRecap,
   formatOrientationText,
 } = require('../orientation');
+const { recordContextLoaded } = require('../grounding/context-events');
 
 const usage = 'Usage: forge recap <issue> [--budget N] [--json]';
 
@@ -35,7 +36,7 @@ function readIssueArg(args) {
 
 // `forge recap <issue>` summarizes a single issue from the deterministic
 // orientation source assembly — it is issue-scoped, not a project-wide recap.
-async function handler(args, _flags, projectRoot) {
+async function handler(args, _flags, projectRoot, opts = {}) {
   const issueId = readIssueArg(args);
   if (!issueId) {
     // Use `error` (not `output`) so the CLI dispatcher prints the usage line
@@ -44,9 +45,22 @@ async function handler(args, _flags, projectRoot) {
     return { success: false, error: usage };
   }
 
-  const recap = buildIssueRecap(projectRoot, issueId, {
-    budgetTokens: readOption(args, '--budget', undefined),
-  });
+  const budget = readOption(args, '--budget', undefined);
+  const recap = buildIssueRecap(projectRoot, issueId, { budgetTokens: budget });
+
+  // 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>`.
+  // Best-effort and awaited so the event is durable before the CLI process exits;
+  // a bookkeeping failure never fails the recap render.
+  const deps = (opts.kernelBroker && opts.kernelDriver)
+    ? { kernelBroker: opts.kernelBroker, kernelDriver: opts.kernelDriver }
+    : undefined;
+  try {
+    await recordContextLoaded(projectRoot, {
+      issueId, cmd: 'recap', budget, session: opts.session, env: opts.env, deps, now: opts.now,
+    });
+  } catch { /* best-effort: never fail a recap on grounding bookkeeping */ }
+
   return {
     success: true,
     output: args.includes('--json') ? `${JSON.stringify(recap, null, 2)}\n` : formatOrientationText(recap),

package/lib/commands/release.js

@@ -4,6 +4,7 @@ const {
   SUPPORTED_TARGET,
   buildReadinessReport,
   renderReadinessReport,
+  writeAuditArtifact,
 } = require('../release-readiness');
 const { runIssueOperation: defaultRunIssueOperation } = require('../forge-issues');
 const { normalizeArgs, normalizeIssueResult, withResolvedIssueBackend } = require('./_issue');
@@ -13,7 +14,7 @@ const { normalizeArgs, normalizeIssueResult, withResolvedIssueBackend } = requir
 // 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]';
+const usage = 'Usage: forge release <id>  |  forge release check --target 0.1.0 [--json]  |  forge release regen-audit';
 
 async function runReleaseIssue(args, projectRoot, opts = {}) {
   const resolved = withResolvedIssueBackend(projectRoot, opts);
@@ -57,6 +58,18 @@ function parseReleaseArgs(args = []) {
 async function handler(args, _flags, projectRoot, opts = {}) {
   const parsed = parseReleaseArgs(args);
 
+  if (parsed.subcommand === 'regen-audit') {
+    // forge release regen-audit — rewrite the D20 kill-list from a live re-scan.
+    // The staleness gate (lib/release-readiness d20 check) points here so a
+    // Beads-removal PR that shifts the census is a one-command fix, not a
+    // hand-edit that red-fails CI until it matches byte-for-byte.
+    const { path: artifact } = writeAuditArtifact(projectRoot);
+    return {
+      success: true,
+      output: `Regenerated ${artifact}. Commit it to clear the d20 staleness gate.\n`,
+    };
+  }
+
   if (parsed.subcommand !== 'check') {
     // forge release <id> — release a claimed issue via the shared issue dispatch.
     return runReleaseIssue(args, projectRoot, opts);

package/lib/commands/remember.js

@@ -3,62 +3,122 @@
 const memoryRouter = require('../memory/router');
 const { stripGlobalFlags } = require('../global-flags');
 
-const usage = 'Usage: forge remember <note> [--tag <label>]... [--json]';
+const usage =
+  'Usage: forge remember <note> [--kind <type>] [--session-summary] [--tag <label>]... ' +
+  '[--what <text>] [--why <text>] [--where <text>] [--learned <text>] [--json]';
+
+// Structured note fields (kernel issue 8cc1db4d). Each is optional and, when present, is
+// folded into the stored note body as a labeled line so it stays FTS-searchable. Order is
+// fixed for a stable, readable render.
+const STRUCTURED_FIELDS = [
+  ['--what', 'What'],
+  ['--why', 'Why'],
+  ['--where', 'Where'],
+  ['--learned', 'Learned'],
+];
+
+// A note's type is stored as a reserved `type:<value>` tag — cheap, additive, and filterable
+// by recall/search WITHOUT a store-schema change (a missing type is fine). The CLI flag is
+// `--kind` (NOT `--type`): `--type` is a reserved GLOBAL flag that bin/forge.js hard-validates
+// against workflow classifications (critical|standard|…), so it can never carry a note type.
+const TYPE_TAG_PREFIX = 'type:';
 
 /**
- * Split positional note words from `--tag <label>` pairs and the `--json` flag.
- * Global flags (e.g. `-p <dir>`) are stripped first so they never leak into
- * the stored note content (kernel issue c1e090ff).
+ * Split positional note words from `--kind`, `--tag <label>`, the structured field flags,
+ * and `--json`. Global flags (e.g. `-p <dir>`) are stripped first so they never leak into the
+ * stored note content (kernel issue c1e090ff); `--kind` is NOT a global flag, so it survives
+ * the strip and is parsed here.
  *
  * @param {string[]} rawArgs - Raw command arguments.
- * @returns {{ note: string, tags: string[], json: boolean }}
+ * @returns {{ note: string, tags: string[], type: (string|undefined), fields: object, json: boolean }}
  */
 function parseArgs(rawArgs) {
   const args = stripGlobalFlags(rawArgs);
+  const fieldFlags = new Map(STRUCTURED_FIELDS.map(([flag, label]) => [flag, label]));
   const words = [];
   const tags = [];
+  const fields = {};
+  let type;
   let json = false;
 
+  // Consume `--flag value` / `--flag=value`, guarding against swallowing the next flag.
+  const takeValue = (index) => {
+    const arg = args[index];
+    const eq = arg.indexOf('=');
+    if (eq >= 0) return { value: arg.slice(eq + 1), consumed: 0 };
+    const next = args[index + 1];
+    if (next && !next.startsWith('--')) return { value: next, consumed: 1 };
+    return { value: undefined, consumed: 0 };
+  };
+
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
+    const bare = arg.startsWith('--') ? arg.split('=', 1)[0] : arg;
     if (arg === '--json') {
       json = true;
-    } else if (arg === '--tag') {
-      const value = args[index + 1];
-      if (value && !value.startsWith('--')) {
-        tags.push(value);
-        index += 1;
-      }
-    } else if (arg.startsWith('--tag=')) {
-      tags.push(arg.slice('--tag='.length));
+    } else if (arg === '--session-summary') {
+      // Memorable one-flag alias for `--kind session-summary` — the explicit capture-on-exit
+      // path an agent calls (via `forge memory add --session-summary` / `forge remember`) to
+      // persist a structured session summary with the same --what/--why/--learned fields.
+      type = 'session-summary';
+    } else if (bare === '--kind') {
+      const { value, consumed } = takeValue(index);
+      if (value) type = value.trim();
+      index += consumed;
+    } else if (bare === '--tag') {
+      const { value, consumed } = takeValue(index);
+      if (value) tags.push(value);
+      index += consumed;
+    } else if (fieldFlags.has(bare)) {
+      const { value, consumed } = takeValue(index);
+      if (value) fields[fieldFlags.get(bare)] = value.trim();
+      index += consumed;
     } else {
       words.push(arg);
     }
   }
 
-  return { note: words.join(' ').trim(), tags, json };
+  return { note: words.join(' ').trim(), tags, type, fields, json };
+}
+
+/**
+ * Compose the stored note body from the positional note plus any structured fields. Fields
+ * are appended as labeled lines under the note so recall renders them readably and they stay
+ * searchable. Returns the empty string only when nothing at all was provided.
+ */
+function composeBody(note, fields) {
+  const lines = STRUCTURED_FIELDS
+    .map(([, label]) => (fields[label] ? `${label}: ${fields[label]}` : null))
+    .filter(Boolean);
+  return [note, ...lines].filter(Boolean).join('\n');
 }
 
 async function handler(args, _flags, projectRoot) {
-  const { note, tags, json } = parseArgs(args);
+  const { note, tags, type, fields, json } = parseArgs(args);
+  const body = composeBody(note, fields);
 
-  if (!note) {
+  if (!body) {
     return {
       success: false,
       error: `No note provided.\n${usage}`,
     };
   }
 
-  const entry = memoryRouter.append(projectRoot, note, { tags });
+  // The type rides as a reserved tag so it is stored and filterable without a schema change.
+  const allTags = type ? [...tags, `${TYPE_TAG_PREFIX}${type}`] : tags;
+  const entry = memoryRouter.append(projectRoot, body, { tags: allTags });
 
   if (json) {
-    return { success: true, output: `${JSON.stringify(entry, null, 2)}\n` };
+    const payload = type ? { ...entry, type } : entry;
+    return { success: true, output: `${JSON.stringify(payload, null, 2)}\n` };
   }
 
-  const tagSuffix = entry.tags.length > 0 ? ` [${entry.tags.join(', ')}]` : '';
+  const userTags = entry.tags.filter(tag => !tag.startsWith(TYPE_TAG_PREFIX));
+  const tagSuffix = userTags.length > 0 ? ` [${userTags.join(', ')}]` : '';
+  const typePrefix = type ? `(${type}) ` : '';
   return {
     success: true,
-    output: `Remembered: ${entry.note}${tagSuffix}`,
+    output: `Remembered: ${typePrefix}${entry.note}${tagSuffix}`,
   };
 }
 
@@ -67,7 +127,13 @@ module.exports = {
   description: 'Persist a project-memory note to the kernel-backed memory store',
   usage,
   flags: {
+    '--kind': 'Type the note (decision|bugfix|gotcha|...) — filterable by recall (--type is reserved)',
+    '--session-summary': 'Alias for --kind session-summary — capture a session summary on exit',
     '--tag': 'Attach a search label (repeatable)',
+    '--what': 'Structured field: what happened/changed',
+    '--why': 'Structured field: why',
+    '--where': 'Structured field: where (file/area)',
+    '--learned': 'Structured field: what was learned',
     '--json': 'Emit machine-readable JSON output',
   },
   handler,

package/lib/commands/setup.js

@@ -378,13 +378,13 @@ async function finalizeWorkflowConfig(options = {}) {
 
 /**
  * Default init runner for finalizeWorkflowConfig. When `skipSideEffects` is set
- * (setup paths that already installed git hooks and migrated Beads), pass no-op
- * deps so init only writes `.forge/config.yaml` instead of re-doing that work —
- * avoids duplicate side effects and warning noise (CodeRabbit on PR #368).
+ * (setup paths that already installed git hooks), pass no-op deps so init only
+ * writes `.forge/config.yaml` instead of re-doing that work — avoids duplicate
+ * side effects and warning noise (CodeRabbit on PR #368).
  */
 function defaultRunInit(root, skipSideEffects) {
   const deps = skipSideEffects
-    ? { installHooks: () => {}, autoMigrateBeads: () => {} }
+    ? { installHooks: () => {} }
     : {};
   return initCommand.handler(['--yes'], {}, root, deps);
 }
@@ -2734,6 +2734,102 @@ function installForgeHookScripts() {
 // kept shipping the broken behaviour. They are imported at the top of this file and
 // re-exported below for the existing test surface.
 
+// Honest, resolved-config description of what the installed hooks will actually
+// enforce (issue eda6d866). The hook scripts are installed unconditionally but are
+// INERT when their gate/rail is disabled in .forge/config.yaml, so setup must not
+// claim "enforcement active" when the resolved config says otherwise.
+// Resolve — from the SAME .forge/config.yaml the hooks read at run time — whether the TDD
+// gate is active and how many protected paths are guarded. The reporting/exit layer gates
+// its verdict on this so setup never claims (or fails over) a state the user deliberately
+// disabled (issue eda6d866). On resolver THROW (missing/corrupt config), fail TOWARD
+// enforcement (tddActive:true, resolved:false) so a broken config can never silently
+// downgrade the human-facing verdict.
+function resolveHookEnforcementState(root = projectRoot) {
+  try {
+    const { getResolvedRuntimeGraph } = require('../core/runtime-graph');
+    const graph = getResolvedRuntimeGraph({ projectRoot: root });
+    const tddRail = (graph.rails || []).find(rail => rail.id === 'rail.tdd_intent');
+    const tddActive = !tddRail || tddRail.enabled !== false;
+    const protectedCount = Array.isArray(graph.protectedPaths) ? graph.protectedPaths.length : 0;
+    return { tddActive, protectedCount, resolved: true };
+  } catch {
+    return { tddActive: true, protectedCount: 0, resolved: false };
+  }
+}
+
+function describeHookEnforcement(root = projectRoot) {
+  const state = resolveHookEnforcementState(root);
+  if (!state.resolved) {
+    return null; // never let an honest-status line block setup (resolver threw)
+  }
+  const tdd = state.tddActive ? 'active' : 'disabled in config (hook inert)';
+  const pp = state.protectedCount > 0
+    ? `active (${state.protectedCount} path${state.protectedCount === 1 ? '' : 's'})`
+    : 'disabled in config (hook inert)';
+  return `TDD gate: ${tdd}; protected-path: ${pp}`;
+}
+
+// Pure reporting/exit-layer verdict (issue eda6d866): fold the file-presence hook check
+// (verifyHooksActive) and the resolved config state (resolveHookEnforcementState) into the
+// message/level and whether setup should exit non-zero. Kept pure + exported so the four
+// honesty cases are unit-testable without spawning setup. The caller folds "are we in a git
+// repo" into `loud`, so a non-git dir (nothing to hook into) only ever warns.
+function buildHookVerdict(verdict, state, options = {}) {
+  const loud = options.loud === true;
+  const tddActive = !state || state.tddActive !== false;
+  if (verdict.active) {
+    if (tddActive) {
+      return {
+        message: `  ✓ Git hook enforcement active (${verdict.method}).`,
+        level: 'log',
+        exitFailure: false,
+      };
+    }
+    // Hooks installed but the TDD gate is OFF in config → the scripts are inert by the
+    // user's own choice. Say so honestly instead of over-claiming "enforcement active".
+    return {
+      message: `  ✓ Git hooks installed (${verdict.method}) — TDD gate disabled in .forge/config.yaml, hooks are inert. Re-enable: forge gate enable rail.tdd_intent`,
+      level: 'log',
+      exitFailure: false,
+    };
+  }
+  if (!tddActive) {
+    // Hooks not active AND the user disabled enforcement — this is the CHOSEN state (e.g.
+    // `init --profile minimal`), so never banner or exit non-zero for it, even under loud.
+    return {
+      message: '  ℹ Git hooks not active — enforcement is disabled in .forge/config.yaml anyway.',
+      level: 'info',
+      exitFailure: false,
+    };
+  }
+  // TDD is ON but hooks are inert — the silent-inert bug B3. Loud setup in a git repo fails
+  // LOUDLY + non-zero; otherwise (init/repair path, or non-git dir folded into !loud) warn.
+  if (loud) {
+    const addCmd = PKG_MANAGER === 'bun'
+      ? 'bun add -d'
+      : PKG_MANAGER === 'npm'
+        ? 'npm install --save-dev'
+        : `${PKG_MANAGER} add -D`;
+    const message = [
+      '',
+      '  ============================================================',
+      '  ⚠ TDD ENFORCEMENT IS NOT ACTIVE',
+      `     ${verdict.reason || 'no pre-commit hook is installed'}.`,
+      '     `forge ship` will block until hooks are active. To fix:',
+      `       ${addCmd} lefthook  &&  npx lefthook install`,
+      '     (or re-run `forge setup` in the repo root).',
+      '  ============================================================',
+      '',
+    ].join('\n');
+    return { message, level: 'error', exitFailure: true };
+  }
+  return {
+    message: `  ⚠ TDD enforcement is NOT active: ${verdict.reason || 'no pre-commit hook installed'}.`,
+    level: 'warn',
+    exitFailure: false,
+  };
+}
+
 function installGitHooks(options = {}) { // NOSONAR — Extracted as-is from bin/forge.js; complexity reduction deferred
   // loud=true (the `forge setup` handlers — quickSetup + executeSetup) surfaces an
   // inert-hooks result as a HARD failure — a banner + non-zero exit — so setup never ends
@@ -2742,13 +2838,27 @@ function installGitHooks(options = {}) { // NOSONAR — Extracted as-is from bin
   // init deliberately degrades to a warning rather than failing, and repair runs inside
   // another command's flow.
   const loud = options.loud === true;
-  console.log('Installing git hooks (TDD enforcement)...');
+  // Honest header: when the TDD gate is disabled in config the hooks install but are inert,
+  // so don't announce "(TDD enforcement)" for a state the user turned off (issue eda6d866).
+  console.log(
+    resolveHookEnforcementState(projectRoot).tddActive
+      ? 'Installing git hooks (TDD enforcement)...'
+      : 'Installing git hooks (TDD gate disabled in config — hooks will be inert)...'
+  );
 
   // Install the Forge hook SCRIPTS first, unconditionally: they back BOTH the lefthook
   // pre-commit gate AND the native harness hooks that forge setup renders regardless of
   // whether the lefthook binary is present.
   installForgeHookScripts();
 
+  // Report what the hooks will ACTUALLY enforce given the resolved config — a
+  // disabled gate/rail installs an inert hook, so say so instead of over-claiming.
+  const enforcementStatus = describeHookEnforcement();
+  if (enforcementStatus) {
+    console.log(`  Enforcement (from .forge/config.yaml): ${enforcementStatus}`);
+  }
+
+  // Skip lefthook.yml creation if binary is not available
   const lefthookStatus = checkLefthookStatus(projectRoot);
   let lefthookInstalled = false;
   if (!lefthookStatus.binaryAvailable && lefthookStatus.message) {
@@ -2826,29 +2936,24 @@ function installGitHooks(options = {}) { // NOSONAR — Extracted as-is from bin
   }
 
   const verdict = verifyHooksActive(projectRoot);
-  if (verdict.active) {
-    console.log(`  ✓ Git hook enforcement active (${verdict.method}).`);
-  } else if (loud && resolveGitHooksDir(projectRoot)) {
-    // In a git repo but enforcement is inert — the exact silent-inert bug B3 kills.
-    // Fail LOUDLY and non-zero so `forge setup` never ends green with hooks off.
-    // (A non-git dir has nothing to hook into, so it only warns — see the else.)
-    const addCmd = PKG_MANAGER === 'bun'
-      ? 'bun add -d'
-      : PKG_MANAGER === 'npm'
-        ? 'npm install --save-dev'
-        : `${PKG_MANAGER} add -D`;
-    console.error('');
-    console.error('  ============================================================');
-    console.error('  ⚠ TDD ENFORCEMENT IS NOT ACTIVE');
-    console.error(`     ${verdict.reason || 'no pre-commit hook is installed'}.`);
-    console.error('     `forge ship` will block until hooks are active. To fix:');
-    console.error(`       ${addCmd} lefthook  &&  npx lefthook install`);
-    console.error('     (or re-run `forge setup` in the repo root).');
-    console.error('  ============================================================');
-    console.error('');
-    process.exitCode = 1;
+  const state = resolveHookEnforcementState(projectRoot);
+  // A non-git dir has nothing to hook into, so it must only ever WARN (never banner/exit).
+  // Fold that into `loud` before building the verdict so buildHookVerdict stays pure. When
+  // the TDD gate is disabled in config, the verdict is info-level with no failure exit even
+  // under loud setup — enforcement honestly follows the resolved config (issue eda6d866).
+  const inGitRepo = Boolean(resolveGitHooksDir(projectRoot));
+  const built = buildHookVerdict(verdict, state, { loud: loud && inGitRepo });
+  if (built.level === 'error') {
+    console.error(built.message);
+  } else if (built.level === 'warn') {
+    console.warn(built.message);
+  } else if (built.level === 'info') {
+    console.info(built.message);
   } else {
-    console.warn(`  ⚠ TDD enforcement is NOT active: ${verdict.reason || 'no pre-commit hook installed'}.`);
+    console.log(built.message);
+  }
+  if (built.exitFailure) {
+    process.exitCode = 1;
   }
 }
 
@@ -3258,44 +3363,6 @@ function configureDefaultExternalServices(skipExternal) {
   console.log('Configuration saved to .env.local');
 }
 
-// Auto-import an existing Beads store into the Kernel during setup.
-// Idempotent and CLI-free: reuses the `forge migrate --from beads` spine, which
-// reads the committed Beads jsonl sidecars directly (no external issue-tracker
-// binary), so it works even when the legacy SQL backend is offline. Failures
-// degrade to a setup note rather than aborting setup. Returns the migrate
-// outcome for callers/tests.
-async function autoMigrateBeadsToKernel(opts = {}) {
-  const migrateModule = require('./migrate');
-  let outcome;
-  try {
-    outcome = await migrateModule.autoMigrateBeadsIfPresent(projectRoot, opts);
-  } catch (err) {
-    addSetupNote(`Beads → Kernel auto-migration failed: ${err.message}`);
-    return { migrated: false };
-  }
-
-  if (!outcome.migrated) {
-    if (outcome.result && outcome.result.success === false) {
-      addSetupNote(`Beads → Kernel auto-migration skipped: ${outcome.result.error}`);
-    }
-    return outcome;
-  }
-
-  const { imported, gaps } = outcome.result;
-  const inserted = imported.issues.inserted;
-  const skipped = imported.issues.skipped;
-  if (inserted > 0) {
-    let line = `  ✓ Migrated ${inserted} issue(s) from Beads to the Kernel`;
-    if (gaps && gaps.count > 0) {
-      line += ` (${gaps.count} field gap(s): ${gaps.items.map(g => g.field).join(', ')})`;
-    }
-    console.log(line);
-  } else {
-    console.log(`  ✓ Beads store already present in the Kernel (${skipped} issue(s))`);
-  }
-  return outcome;
-}
-
 // Install git hooks for a target project root without a full setup run.
 // Reuses the same lefthook install path setup performs so `forge init` can
 // reach a hook-active state (closing the init → HOOKS_NOT_ACTIVE catch-22).
@@ -3363,9 +3430,6 @@ async function quickSetup(selectedAgents, skipExternal) {
   // Auto-setup project tools (Kernel issue store, Skills)
   await autoSetupToolsInQuickMode();
 
-  // Auto-import an existing Beads store into the Kernel (idempotent, CLI-free)
-  await autoMigrateBeadsToKernel();
-
   // Setup Claude first if selected, then setup remaining agents
   if (selectedAgents.includes('claude')) {
     await setupAgent('claude');
@@ -3905,9 +3969,6 @@ async function executeSetup(config) {
   console.log('');
   installGitHooks({ loud: true });
 
-  // Auto-import an existing Beads store into the Kernel (idempotent, CLI-free)
-  await autoMigrateBeadsToKernel();
-
   // External services (unless skipped)
   await handleExternalServices(skipExternal, agents);
 
@@ -4319,6 +4380,9 @@ module.exports = {
   },
 
   // Expose internals for testing and cross-command use
+  describeHookEnforcement,
+  resolveHookEnforcementState,
+  buildHookVerdict,
   checkPrerequisites,
   setupCoreDocs,
   displaySetupSummary,
@@ -4340,7 +4404,6 @@ module.exports = {
   installViaBunx,
   autoInstallLefthook,
   autoSetupToolsInQuickMode,
-  autoMigrateBeadsToKernel,
   ensureGitHooksInstalled,
   forgeShouldWriteLefthookConfig,
   FORGE_USER_LEFTHOOK_YML,