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

package/lib/commands/_aliases.js

@@ -0,0 +1,248 @@
+/**
+ * Command Aliases — declarative back-compat alias map.
+ *
+ * Generalises the former hardcoded `ISSUE_ALIAS_COMMANDS` allowlist (bin/forge.js)
+ * into a single declarative source of truth for command-surface unification
+ * (kernel issue 33d1a906, epic eea186fa). Each entry maps a bare top-level alias
+ * to the canonical `<noun> <sub>` form it stands in for, plus two flags:
+ *
+ *   { canonical: 'issue create', visible: false, deprecated?: true }
+ *
+ *   - `canonical`  — the canonical noun+subcommand this alias resolves to.
+ *   - `visible`    — true → routable AND shown in `forge --help`;
+ *                    false → routable but hidden from help (back-compat only).
+ *   - `deprecated` — optional; when true, using the alias emits a one-line hint
+ *                    to STDERR, but ONLY when `FORGE_DEPRECATION_WARNINGS` is set.
+ *                    Aliases are NEVER removed or broken (docker still ships
+ *                    `docker pull`).
+ *
+ * P0 SCOPE: seeds ONLY the existing issue aliases migrated verbatim from
+ * `ISSUE_ALIAS_COMMANDS` (all hidden, none deprecated) so behaviour is identical.
+ * No new noun mappings are added here — those land in later phases. The bare
+ * files (create.js, update.js, …) still exist and remain the routed handlers, so
+ * `resolveDispatch` is a strict no-op for the seed set (its first clause skips any
+ * name that is still a registered command).
+ *
+ * Files starting with `_` are excluded from command auto-discovery (see
+ * `_registry.js`), so this module is never mistaken for a command itself.
+ *
+ * @module _aliases
+ */
+
+/**
+ * @typedef {Object} AliasDescriptor
+ * @property {string} canonical - Canonical `<noun> <sub>` form the alias resolves to.
+ * @property {boolean} visible - Whether the alias appears in `forge --help`.
+ * @property {boolean} [deprecated] - Whether using the alias emits an opt-in hint.
+ */
+
+/** @type {Object<string, AliasDescriptor>} */
+const ALIASES = {
+  create: { canonical: 'issue create', visible: false },
+  update: { canonical: 'issue update', visible: false },
+  claim: { canonical: 'issue claim', visible: false },
+  close: { canonical: 'issue close', visible: false },
+  show: { canonical: 'issue show', visible: false },
+  list: { canonical: 'issue list', visible: false },
+  ready: { canonical: 'issue ready', visible: false },
+  blocked: { canonical: 'issue blocked', visible: false },
+  stale: { canonical: 'issue stale', visible: false },
+  orphans: { canonical: 'issue orphans', visible: false },
+  lint: { canonical: 'issue lint', visible: false },
+  claims: { canonical: 'issue claims', visible: false },
+  // `issues` is the plural convenience form of `issue list`.
+  issues: { canonical: 'issue list', visible: false },
+
+  // P1 (kernel issue febf7690) — memory noun shortcuts. The `memory` noun
+  // (add/recall/search/insights) shipped in PR #392 (issue 25362344); P1 wires the
+  // bare verbs as VISIBLE back-compat shortcuts of the canonical `memory <sub>`
+  // form. The canonical WRITE verb is `memory add` (there is NO `save`). These stay
+  // registered command files (remember.js/recall.js/insights.js), so resolveDispatch
+  // is a strict no-op for them and bare-verb dispatch stays byte-identical; the
+  // entries exist to document the mapping and drive the `forge --help` Shortcuts
+  // block. They are deliberately NOT issue-backend flag-passthrough aliases (see
+  // passthroughAliasNames) so global flags (`-p`, `--help`, `--all`) still parse
+  // exactly as they did for the standalone commands.
+  remember: { canonical: 'memory add', visible: true },
+  recall: { canonical: 'memory recall', visible: true },
+  insights: { canonical: 'memory insights', visible: true },
+
+  // P2 (kernel issue 6ab3f30c) — the `pr` noun (ship/preflight/shepherd/merge) plus
+  // folding doc-gate under the existing `gate` noun. `pr ship` is the canonical
+  // PR-creation form, but bare `ship` stays a VISIBLE shortcut (hot workflow verb,
+  // zero keystroke loss); `preflight` is likewise VISIBLE. shepherd/merge/doc-gate
+  // are less-hot, so they stay HIDDEN back-compat aliases. Every one keeps its own
+  // registered command file (ship.js/preflight.js/shepherd.js/merge.js/doc-gate.js),
+  // so resolveDispatch is a strict no-op for them and bare-verb dispatch stays
+  // byte-identical — the entries document the mapping and drive the `forge --help`
+  // Shortcuts block. Their canonical is a `pr `/`gate ` form (NOT `issue `), so
+  // passthroughAliasNames() excludes them and their global flags (`--pull`,
+  // `--json`, `--bundle`, `--all`, `-h`) parse exactly as the standalone commands'.
+  ship: { canonical: 'pr ship', visible: true },
+  preflight: { canonical: 'pr preflight', visible: true },
+  shepherd: { canonical: 'pr shepherd', visible: false },
+  merge: { canonical: 'pr merge', visible: false },
+  'doc-gate': { canonical: 'gate doc', visible: false },
+};
+
+/**
+ * Look up an alias descriptor by bare name.
+ * @param {string} name
+ * @returns {AliasDescriptor|undefined}
+ */
+function resolveAlias(name) {
+  return Object.prototype.hasOwnProperty.call(ALIASES, name) ? ALIASES[name] : undefined;
+}
+
+/**
+ * @param {string} name
+ * @returns {boolean} true if `name` is a registered alias.
+ */
+function isAlias(name) {
+  return resolveAlias(name) !== undefined;
+}
+
+/**
+ * All alias names. Replaces the flat `ISSUE_ALIAS_COMMANDS` array — used to skip
+ * global flag parsing so passthrough flags reach the handler intact.
+ * @returns {string[]}
+ */
+function aliasNames() {
+  return Object.keys(ALIASES);
+}
+
+/**
+ * The subset of aliases that delegate ALL flag parsing to the issue backend
+ * and therefore must SKIP global flag parsing in bin/forge.js so flags like
+ * `--type` / `-p` / `--help` reach the handler intact. This is issue-specific:
+ * only issue-canonical aliases passthrough. Non-issue aliases (e.g. the P1 memory
+ * shortcuts) parse global flags normally — exactly as their standalone command
+ * files did — so their behaviour stays byte-identical after becoming aliases.
+ * @returns {string[]}
+ */
+function passthroughAliasNames() {
+  return Object.keys(ALIASES).filter(name => ALIASES[name].canonical.startsWith('issue '));
+}
+
+/**
+ * Names of aliases shown in the `forge --help` Shortcuts block — visible
+ * back-compat shortcuts for a canonical `<noun> <sub>` form. Hidden (back-compat
+ * only) aliases are excluded.
+ * @returns {string[]}
+ */
+function visibleAliasNames() {
+  return Object.keys(ALIASES).filter(name => ALIASES[name].visible === true);
+}
+
+/**
+ * Whether a descriptor is hidden from help. Pure predicate over the `visible`
+ * flag so the visible-vs-hidden distinction can be tested independent of the
+ * P0 seed (which is entirely hidden).
+ * @param {AliasDescriptor|undefined} descriptor
+ * @returns {boolean}
+ */
+function isHidden(descriptor) {
+  return !!descriptor && descriptor.visible === false;
+}
+
+/**
+ * Whether the named alias is hidden from `forge --help`. Drives the help filter.
+ * @param {string} name
+ * @returns {boolean}
+ */
+function isHiddenAlias(name) {
+  return isHidden(resolveAlias(name));
+}
+
+/**
+ * Whether the named alias is a visible (help-listed) shortcut.
+ * @param {string} name
+ * @returns {boolean}
+ */
+function isVisibleAlias(name) {
+  const descriptor = resolveAlias(name);
+  return !!descriptor && descriptor.visible === true;
+}
+
+/**
+ * Render the one-line deprecation hint for an alias.
+ * @param {string} name
+ * @param {AliasDescriptor} descriptor
+ * @returns {string}
+ */
+function renderHint(name, descriptor) {
+  return `forge ${name} is a back-compat alias; prefer 'forge ${descriptor.canonical}'`;
+}
+
+/**
+ * Whether a deprecation hint should be emitted: requires BOTH the opt-in env flag
+ * AND a descriptor explicitly marked deprecated. Default (flag unset) is silent,
+ * so scripted stdout is never affected.
+ * @param {AliasDescriptor|undefined} descriptor
+ * @param {Object} env
+ * @returns {boolean}
+ */
+function shouldWarn(descriptor, env) {
+  return !!(env && env.FORGE_DEPRECATION_WARNINGS && descriptor && descriptor.deprecated);
+}
+
+/**
+ * Emit an opt-in deprecation hint to stderr when both gates pass. Never writes to
+ * stdout (would corrupt `--json`). Returns whether a hint was emitted.
+ * @param {string} name
+ * @param {{env?: Object, stderr?: {write: function}, resolve?: function}} [opts]
+ * @returns {boolean}
+ */
+function maybeWarnDeprecation(name, opts = {}) {
+  const env = opts.env || process.env;
+  const stderr = opts.stderr || process.stderr;
+  const resolve = opts.resolve || resolveAlias;
+  const descriptor = resolve(name);
+  if (!shouldWarn(descriptor, env)) return false;
+  stderr.write(`${renderHint(name, descriptor)}\n`);
+  return true;
+}
+
+/**
+ * Resolve a bare command to its canonical noun handler for dispatch.
+ *
+ * A command that is still a registered command file (`isRegistered(command)` is
+ * true) is NEVER rewritten — dispatch stays byte-identical. Only a bare alias
+ * whose name is NOT a registered command resolves to `<noun> <sub>`; this
+ * activates when a later phase folds a bare verb into a noun handler. For the P0
+ * seed every alias is still registered, so this always returns `redirected:false`.
+ *
+ * @param {string} command - The bare command name (args[0]).
+ * @param {string[]} argv - The full argv (argv[0] is the command token).
+ * @param {function(string): boolean} isRegistered - Predicate: is this a live command?
+ * @returns {{command: string, args: string[], redirected: boolean}}
+ */
+function resolveDispatch(command, argv, isRegistered) {
+  if (typeof isRegistered === 'function' && isRegistered(command)) {
+    return { command, args: argv, redirected: false };
+  }
+  const descriptor = resolveAlias(command);
+  if (!descriptor) {
+    return { command, args: argv, redirected: false };
+  }
+  const parts = String(descriptor.canonical).trim().split(/\s+/);
+  const noun = parts[0];
+  const rest = Array.isArray(argv) ? argv.slice(1) : [];
+  return { command: noun, args: [noun, ...parts.slice(1), ...rest], redirected: true };
+}
+
+module.exports = {
+  ALIASES,
+  resolveAlias,
+  isAlias,
+  aliasNames,
+  passthroughAliasNames,
+  visibleAliasNames,
+  isHidden,
+  isHiddenAlias,
+  isVisibleAlias,
+  renderHint,
+  shouldWarn,
+  maybeWarnDeprecation,
+  resolveDispatch,
+};

package/lib/commands/_issue.js

@@ -2,6 +2,7 @@
 
 const { runIssueOperation: defaultRunIssueOperation } = require('../forge-issues');
 const { resolveIssueBackend, hasExplicitBackendSignal, shouldUseKernelBroker } = require('../issue-backend');
+const { maybeWarnUnmigratedBeads } = require('../beads-nudge');
 const {
   ISSUE_COMMAND_SCHEMA_VERSION,
   ISSUE_COMMAND_ERROR_SCHEMA_VERSION,
@@ -12,6 +13,8 @@ const {
 const { getResolvedRuntimeGraph } = require('../core/runtime-graph');
 const { renderIssueEnvelope } = require('../issue-render');
 const { recordStageTransition } = require('../workflow/stage-transition');
+const { checkReadFirst } = require('../grounding/read-first');
+const { recordContextLoaded } = require('../grounding/context-events');
 
 // The Forge issue command surface. Each subcommand routes through the shared
 // runIssueOperation, which selects the active backend (Kernel by --kernel /
@@ -731,6 +734,21 @@ async function runIssueSubcommand(subcommand, args, projectRoot, rawOpts = {}) {
 
   const opts = withResolvedIssueBackend(projectRoot, rawOpts);
 
+  // gate.read_first (grounding, epic 6ef96e92): HARD-BLOCK `forge claim <id>`
+  // until the issue has been read this session/window (a `context.loaded` kernel
+  // event exists — appended by `forge recap`/`forge show`). Fail-closed: the
+  // cheapest path through the gate is the correct behavior, since the remedy
+  // (`forge recap <id>`) also injects the context. Consulted here at the command
+  // boundary exactly like gate.issue_verify; rail.grounding/gate.read_first
+  // disabled -> allow (logged). Read commands never gate; only `claim` in P1.
+  if (subcommand === 'claim') {
+    const issueId = normalizeArgs(args).find((arg) => !arg.startsWith('--'));
+    if (issueId) {
+      const block = await checkReadFirst(projectRoot, issueId, opts);
+      if (block) return block;
+    }
+  }
+
   // Both backends are reached through the same runIssueOperation seam. Naming the
   // injected local `runIssueOperation` keeps the dispatch a literal call to a binding
   // named `runIssueOperation` (the kernel-evidence gate is syntactic) while still
@@ -769,6 +787,27 @@ async function runIssueSubcommand(subcommand, args, projectRoot, rawOpts = {}) {
   }
   // Best-effort, non-blocking: mirror a stage-transition comment into stage_runs.
   recordStageTransitionFromComment(subcommand, operationArgs, result, opts);
+  // Best-effort, non-blocking: nudge a returning 0.0.10 user whose empty Kernel
+  // read hides an unmigrated legacy issue store (kernel issue a5399f3d). The hint
+  // text lives in lib/beads-nudge.js so this hot path stays token-free.
+  maybeWarnUnmigratedBeads(subcommand, result, projectRoot, rawOpts);
+  // Grounding (gate.read_first): a successful `forge show <id>` counts as reading
+  // the issue, so append a `context.loaded` event. Best-effort and awaited (a
+  // fire-and-forget append could lose the event when the CLI process exits); a
+  // failure here never fails the read.
+  if (subcommand === 'show' && result && result.ok === true) {
+    const shownId = normalizeArgs(args).find((arg) => !arg.startsWith('--'));
+    if (shownId) {
+      const deps = (opts.kernelBroker && opts.kernelDriver)
+        ? { kernelBroker: opts.kernelBroker, kernelDriver: opts.kernelDriver }
+        : undefined;
+      try {
+        await recordContextLoaded(projectRoot, {
+          issueId: shownId, cmd: 'show', session: opts.session, env: opts.env, deps, now: opts.now,
+        });
+      } catch { /* best-effort: never fail a read on grounding bookkeeping */ }
+    }
+  }
   // Contract output is opt-in for the human-first reads: an explicit --json flag
   // or FORGE_JSON=1 in the environment (for scripts that cannot alter argv).
   const jsonRequested = normalizeArgs(args).includes('--json')

package/lib/commands/_manifest.js

@@ -48,6 +48,7 @@ const commands = [
   { file: "issues.js", module: require("./issues") },
   { file: "lint.js", module: require("./lint") },
   { file: "list.js", module: require("./list") },
+  { file: "memory.js", module: require("./memory") },
   { file: "merge.js", module: require("./merge") },
   { file: "migrate.js", module: require("./migrate") },
   { file: "new.js", module: require("./new") },
@@ -56,6 +57,7 @@ const commands = [
   { file: "orphans.js", module: require("./orphans") },
   { file: "patch.js", module: require("./patch") },
   { file: "plan.js", module: require("./plan") },
+  { file: "pr.js", module: require("./pr") },
   { file: "preflight.js", module: require("./preflight") },
   { file: "prime.js", module: require("./prime") },
   { file: "push.js", module: require("./push") },

package/lib/commands/_registry.js

@@ -12,6 +12,7 @@
 const { existsSync, readdirSync } = require('node:fs');
 const path = require('node:path');
 const { normalizeStageId } = require('../workflow/stages');
+const { ensureForgeHome, isMutatingVerb } = require('../activation/ensure-forge-home');
 
 // Static command manifest (bundleable fast path). This is a static require so
 // `bun build --compile` can bundle the command graph; the file is generated by
@@ -199,6 +200,19 @@ async function executeCommand(commands, commandName, args, flags, projectRoot, o
       }
     }
 
+    // Lazy `.forge/` home (activation foundation): the FIRST mutating verb in a
+    // bare repo materializes the gates-disabled skeleton on demand. Read-only
+    // verbs never enter this branch, so they write nothing; an already-inited
+    // repo is a no-op (never clobbered). Failure to create the home must not
+    // crash the command — degrade to a warning. Opt out via `skipEnsureHome`.
+    if (projectRoot && options.skipEnsureHome !== true && isMutatingVerb(commandName, command)) {
+      try {
+        (options.ensureForgeHome || ensureForgeHome)(projectRoot);
+      } catch (err) {
+        console.warn(`[forge] Could not initialize .forge/ home: ${err?.message ?? err}`);
+      }
+    }
+
     // Forward a resolved per-command opts object as the handler's 4th arg. Issue/
     // alias handlers read it (shouldUseKernelBroker(opts)); other handlers ignore
     // it. Backward-compatible: defaults to {} so existing 3-arg handlers are

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

@@ -145,27 +145,6 @@ 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.
-  }
-}
-
 /**
  * Resolve the command opts and selector-stripped args for a dispatched command.
  *
@@ -195,9 +174,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 };
@@ -236,13 +212,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/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,17 @@ const {
   renderGlobalHookBlock,
   installGlobalHooks,
 } = require('../hook-global-installer');
-const { sessionStartCapability, userPromptSubmitCapability } = require('../hook-renderer');
-const { collectDigestData, buildMemoryDigest } = require('../memory-digest');
+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');
 
 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 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 +49,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') {
@@ -126,6 +171,94 @@ 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 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 +355,12 @@ 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 === '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()}`,
   };
 }