forge-workflow 0.1.0-beta.2 → 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,28 +143,20 @@ function resolveFlagBackend(flags = {}) {
     );
   }
 
-  return fromKernel || fromBackend || null;
-}
-
-// Run the first-use Beads import safety net for a kernel-routed command. Resolving the
-// migrate module lives INSIDE the try so even a require() failure (missing/corrupt
-// module) can never break command-opts resolution — the whole point of the safety net.
-// Shared by both kernel branches (issue + KERNEL_TOOL_COMMANDS) so the two call sites
-// cannot drift.
-async function runRuntimeAutoMigrate(deps, kernelDeps) {
-  try {
-    const autoMigrate = deps.autoMigrateBeadsAtRuntime
-      || require('./migrate').autoMigrateBeadsAtRuntime;
-    await autoMigrate({
-      projectRoot: deps.projectRoot,
-      databasePath: kernelDeps.kernelDatabasePath,
-      broker: kernelDeps.kernelBroker,
-      driver: kernelDeps.kernelDriver,
-    });
-  } catch {
-    // A migration-hook failure (including a require() failure) must never break the
-    // command it rides on.
+  // 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;
 }
 
 /**
@@ -195,9 +188,6 @@ async function resolveCommandOpts(command, rawArgs = [], deps = {}) {
         databasePath: deps.databasePath,
         gitCommonDir: deps.gitCommonDir,
       });
-      // Same first-use safety net as the issue branch: an export-first upgrader would
-      // otherwise drain an EMPTY kernel and never trigger the one-time Beads import.
-      await runRuntimeAutoMigrate(deps, kernelDeps);
       return { commandOpts: { _broker: kernelDeps.kernelBroker }, args: rawArgs };
     } catch {
       return { commandOpts: {}, args: rawArgs };
@@ -212,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({
@@ -236,13 +219,6 @@ async function resolveCommandOpts(command, rawArgs = [], deps = {}) {
     gitCommonDir: deps.gitCommonDir,
   });
 
-  // Safety net: the kernel is the default backend, but onboarding auto-migrate runs
-  // only from `forge setup`/`init`. An existing repo whose user merely upgrades forge
-  // would read an EMPTY kernel here and their existing Beads issues would appear to
-  // vanish. Import them ONCE on first kernel use (idempotent, gated by an in-DB marker
-  // that shares the kernel DB lifecycle, stderr only).
-  await runRuntimeAutoMigrate(deps, kernelDeps);
-
   return {
     commandOpts: {
       issueBackend: KERNEL,

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

@@ -29,11 +29,21 @@ const {
   isGateApproved,
 } = require('../gate-events');
 
+// The doc-update gate folds under this noun as `gate doc` (P2, kernel issue
+// 6ab3f30c) — it is a gate concern, not a `pr` one. `doc` delegates to the
+// standalone doc-gate command (same code); bare `forge doc-gate` stays registered
+// as a back-compat alias. Required lazily so the module graph has no cycle and the
+// routed handler is resolved at dispatch time.
+const docGate = require('./doc-gate');
+
 const TOGGLE_ACTIONS = new Set(['enable', 'disable']);
 const EVENT_ACTIONS = new Set(['approve', 'reject', 'status', 'check']);
 
 function usage() {
-  return 'Usage: forge gate <enable|disable|approve|reject|status|check> [<issue-id>] <gate-id> [--reason <text>] [--json]';
+  return [
+    'Usage: forge gate <enable|disable|approve|reject|status|check> [<issue-id>] <gate-id> [--reason <text>] [--json]',
+    '       forge gate doc <detect|check|init|okf|...> [args]   (doc-update gate; = forge doc-gate, run `forge doc-gate --help`)',
+  ].join('\n');
 }
 
 // The known-toggle set is gates PLUS unlocked toggleable rails (e.g.
@@ -165,6 +175,13 @@ async function handleCheck(issueId, gateId, projectRoot, opts) {
 async function handler(args, flags = {}, projectRoot = process.cwd(), opts = {}) {
   const [action, ...rest] = args;
 
+  // `gate doc [<doc-gate sub> ...]` → the standalone doc-gate handler, with the
+  // consumed `doc` token dropped so its own arg shape (detect/check/init/okf …)
+  // and flags (`--base`/`--head`/`--json`/`--skip` …) reach it byte-identically.
+  if (action === 'doc') {
+    return docGate.handler(rest, flags, projectRoot, opts);
+  }
+
   if (TOGGLE_ACTIONS.has(action)) {
     return handleToggle(action, rest[0], projectRoot);
   }
@@ -180,7 +197,7 @@ async function handler(args, flags = {}, projectRoot = process.cwd(), opts = {})
 
   return {
     success: false,
-    error: `Expected 'enable', 'disable', 'approve', 'reject', 'status', or 'check'.\n${usage()}`,
+    error: `Expected 'enable', 'disable', 'approve', 'reject', 'status', 'check', or 'doc'.\n${usage()}`,
   };
 }
 

package/lib/commands/hooks.js

@@ -27,14 +27,82 @@ const {
   renderGlobalHookBlock,
   installGlobalHooks,
 } = require('../hook-global-installer');
-const { sessionStartCapability, userPromptSubmitCapability } = require('../hook-renderer');
-const { collectDigestData, buildMemoryDigest } = require('../memory-digest');
+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)';
+    + '       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)';
 }
 
 /** Parse `--harness <h>` (defaults to claude) from a session-start arg slice. */
@@ -46,6 +114,48 @@ function parseHarness(rest) {
   return 'claude';
 }
 
+/** Parse `--trigger <t>` (defaults to stop) from a capture arg slice. */
+function parseTrigger(rest) {
+  for (let i = 0; i < rest.length; i += 1) {
+    if (rest[i] === '--trigger') return rest[i + 1] || 'stop';
+    if (rest[i].startsWith('--trigger=')) return rest[i].slice('--trigger='.length);
+  }
+  return 'stop';
+}
+
+// Capture bounds — the snapshot is a small NUDGE, not a manual. A hard issue cap + per-title
+// cap + overall body cap keep the note (which is re-injected at the NEXT session's SessionStart
+// digest) token-bounded. Tags mark it a session-summary typed note AND a Forge auto-capture
+// (the latter is the dedupe/idempotency key that stops per-turn Stop flooding).
+const CAPTURE_ISSUE_CAP = 5;
+const CAPTURE_TITLE_CAP = 80;
+const CAPTURE_NOTE_CAP = 1000;
+const CAPTURE_AUTO_TAG = 'forge:auto-capture';
+const CAPTURE_TAGS = ['type:session-summary', CAPTURE_AUTO_TAG];
+
+/**
+ * Build the deterministic, token-bounded capture note body. PURE. The body deliberately
+ * carries NO timestamp (the store stamps its own) so an unchanged session state yields a
+ * byte-identical body across repeated Stops — that identity is what the dedupe keys on.
+ * @param {string} trigger - 'precompact' | 'stop'
+ * @param {object[]} issues - in-progress issues (title/id defensively resolved)
+ * @returns {string}
+ */
+function buildCaptureNote(trigger, issues) {
+  const capped = issues.slice(0, CAPTURE_ISSUE_CAP);
+  const lines = capped.map(issue => {
+    const title = String((issue && (issue.title || issue.id)) || 'untitled').replace(/\s+/g, ' ').trim();
+    return `- ${title.length > CAPTURE_TITLE_CAP ? `${title.slice(0, CAPTURE_TITLE_CAP)}…` : title}`;
+  });
+  const more = issues.length > capped.length ? `\n- …and ${issues.length - capped.length} more` : '';
+  const body = lines.length
+    ? `Session boundary (${trigger}) — in-progress:\n${lines.join('\n')}${more}`
+    : `Session boundary (${trigger}) — no in-progress issues.`;
+  // Reserve one char for the appended ellipsis so the FINAL note (incl. '…') is ≤ the cap,
+  // never CAPTURE_NOTE_CAP + 1.
+  return body.length > CAPTURE_NOTE_CAP ? `${body.slice(0, CAPTURE_NOTE_CAP - 1)}…` : body;
+}
+
 /** Wrap a digest into a harness-native SessionStart payload, or '' when unsupported. */
 function formatSessionStart(harness, text) {
   if (harness === 'claude') {
@@ -70,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. */
@@ -126,6 +254,157 @@ async function handleInboxPickup(rest, projectRoot, opts = {}) {
   }
 }
 
+/**
+ * `forge hooks shepherd-events --harness <h>` — the PR-shepherd CONTEXT hook. On each
+ * prompt it emits harness-native UserPromptSubmit JSON carrying a COMPACT, capped digest
+ * of NEW PR-monitor events (verdict changes, failed checks, new threads, merged/closed)
+ * since the last read across all open-PR journals, then advances the per-PR consumer
+ * cursor so nothing re-surfaces. This is the CONSUMER side of the constant watcher: the
+ * watch loop writes the journal, this pushes the deltas to the working agent. It reads the
+ * user's OWN local journal via a supported hook — it NEVER injects into stdin and NEVER
+ * drives the agent (Anthropic Usage Policy). FAIL-OPEN: any failure, an unsupported
+ * harness, or no new events yields '' (the harness injects nothing). NEVER throws.
+ *
+ * @param {string[]} rest - args after the `shepherd-events` action.
+ * @param {string} projectRoot
+ * @param {object} [opts] - injectable digest collector ({ collectDigest }).
+ * @returns {{ success: boolean, output: string }}
+ */
+function handleShepherdEvents(rest, projectRoot, opts = {}) {
+  try {
+    const harness = parseHarness(rest);
+    const capability = userPromptSubmitCapability(harness);
+    // Honest capability matrix: a non-Claude harness gets an explicit skip
+    // reason as surface-only result metadata (for callers/telemetry) but NEVER
+    // any injected output — `reason` must not drive the agent.
+    if (!capability.rendered) return { success: true, output: '', reason: capability.reason };
+    const collect = opts.collectDigest || collectDigest;
+    const { text } = collect({ root: projectRoot });
+    if (!text) return { success: true, output: '' };
+    return { success: true, output: formatUserPromptSubmit(harness, text) };
+  } catch {
+    // Fail-open: a context hook must never break a prompt.
+    return { success: true, output: '' };
+  }
+}
+
+/**
+ * `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
+ * session-summary note into the memory store BEFORE learnings are lost. This is the WRITE half
+ * of Forge memory (SessionStart only INJECTS). It PERSISTS to the store and emits NO stdout — a
+ * Stop hook that printed text would inject into the turn, and it never drives the agent
+ * (Anthropic Usage Policy). FAIL-OPEN: any failure, an unsupported harness, or nothing worth
+ * capturing yields '' and no write. NEVER throws.
+ *
+ * Flooding guard: a plain Stop with nothing in progress is skipped (Stop fires every turn), and
+ * a byte-identical repeat of the newest auto-capture note is skipped — so only meaningful,
+ * changed session state is written. PreCompact records a boundary even when nothing is in
+ * progress (unlike Stop), but it still goes through the same dedupe — a byte-identical
+ * PreCompact repeat is skipped too.
+ *
+ * @param {string[]} rest - args after the `capture` action.
+ * @param {string} projectRoot
+ * @param {object} [opts] - injectable { fetchIssues, fetchNotes, append } for tests.
+ * @returns {Promise<{ success: boolean, output: string }>}
+ */
+async function handleCapture(rest, projectRoot, opts = {}) {
+  try {
+    const harness = parseHarness(rest);
+    if (!sessionEndCapability(harness).rendered) return { success: true, output: '' };
+    const trigger = parseTrigger(rest);
+
+    const fetchIssues = opts.fetchIssues || defaultFetchIssues;
+    const claimed = await fetchIssues(projectRoot, 'in_progress', opts);
+    const issues = Array.isArray(claimed) ? claimed : [];
+
+    // Stop fires every turn; a plain Stop with nothing in progress is not worth a note.
+    // PreCompact is rare and precedes real context loss, so it records a boundary even with
+    // nothing in progress — but it is NOT exempt from the byte-identical dedupe below.
+    if (trigger !== 'precompact' && issues.length === 0) return { success: true, output: '' };
+
+    const body = buildCaptureNote(trigger, issues);
+
+    // Content dedupe: if the newest auto-capture note is byte-identical, this is a repeat of
+    // an unchanged session — skip the write so the store never floods with duplicates.
+    const fetchNotes = opts.fetchNotes || defaultFetchNotes;
+    const recent = await fetchNotes(projectRoot, { ...opts, noteLimit: 10 });
+    const lastCapture = (Array.isArray(recent) ? recent : [])
+      .find(note => Array.isArray(note && note.tags) && note.tags.includes(CAPTURE_AUTO_TAG));
+    if (lastCapture && lastCapture.note === body) return { success: true, output: '' };
+
+    const append = opts.append || require('../memory/router').append;
+    append(projectRoot, body, { tags: CAPTURE_TAGS });
+    return { success: true, output: '' };
+  } catch {
+    // Fail-open: a capture hook must never break a session.
+    return { success: true, output: '' };
+  }
+}
+
 function parseInstallArgs(rest) {
   const parsed = { global: false, dryRun: false, harness: 'all', unknown: [] };
   for (let i = 0; i < rest.length; i += 1) {
@@ -222,10 +501,13 @@ async function handler(args, flags = {}, projectRoot, opts = {}) {
   const action = args[0];
   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 {
     success: false,
-    error: `forge hooks supports: install, session-start, inbox-pickup.\n${usage()}`,
+    error: `forge hooks supports: install, session-start, inbox-pickup, shepherd-events, capture.\n${usage()}`,
   };
 }