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

package/lib/global-flags.js

@@ -67,8 +67,38 @@ function stripGlobalFlags(args) {
   return kept;
 }
 
+/**
+ * Index of the first positional token (a bare, non-flag argument), skipping any
+ * leading global flags and their consumed values. Returns -1 when no positional
+ * exists. Uses the SAME flag-consumption rules as {@link stripGlobalFlags} so the
+ * two agree on what counts as a positional. Unlike stripGlobalFlags this returns
+ * an index into the ORIGINAL array, so callers can splice out the positional
+ * while preserving the intervening flags.
+ *
+ * @param {string[]} args - Raw command arguments.
+ * @param {number} [start=0] - Index to begin scanning from.
+ * @returns {number} Index into `args` of the first positional token, or -1.
+ */
+function firstPositionalIndex(args, start = 0) {
+  for (let index = start; index < args.length; index += 1) {
+    const arg = args[index];
+    if (GLOBAL_BOOLEAN_FLAGS.has(arg)) continue;
+    if (GLOBAL_VALUE_FLAG_PREFIXES.some((prefix) => arg.startsWith(prefix))) continue;
+    if (GLOBAL_VALUE_FLAGS.has(arg)) {
+      const next = args[index + 1];
+      if (next !== undefined && !next.startsWith('-')) index += 1;
+      continue;
+    }
+    // Any other dash-prefixed token is a non-global flag, not the positional.
+    if (arg.startsWith('-')) continue;
+    return index;
+  }
+  return -1;
+}
+
 module.exports = {
   GLOBAL_BOOLEAN_FLAGS,
   GLOBAL_VALUE_FLAGS,
   stripGlobalFlags,
+  firstPositionalIndex,
 };

package/lib/grounding/context-events.js

@@ -0,0 +1,230 @@
+'use strict';
+
+/**
+ * @module grounding/context-events
+ *
+ * The state primitive behind gate.read_first: "this issue's context was loaded"
+ * recorded as a durable kernel EVENT, structurally identical to gate.approved
+ * (lib/gate-events.js). `forge recap`/`forge show` append a `context.loaded`
+ * event to the issue's stream on a successful render; `forge claim` refuses to
+ * proceed until such an event exists for the issue this session/window.
+ *
+ * Mechanism (mirrors gate-events, deliberately): a PURE APPEND via the driver
+ * primitives (`insertKernelEvent` + `listKernelEvents`), NOT the guarded
+ * issue-mutation pipeline — context.loaded does not mutate the issue, so it must
+ * not participate in the issue-revision CAS. Idempotency is enforced by a
+ * window-bucketed key (so a re-read inside the freshness window mints no
+ * duplicate, but a re-read in the NEXT window mints a fresh event that clears a
+ * re-block) plus the unique idempotency index catching a concurrent race.
+ *
+ * Config-surface note: whether the gate is enabled lives in the runtime graph +
+ * `.forge/config.yaml`; this module only records/reads the events.
+ */
+
+const { resolveOwnedKernel, closeIfOwned } = require('../kernel/owned-kernel');
+const { resolveIssueActor } = require('../forge-issues');
+
+const CONTEXT_LOADED_EVENT = 'context.loaded';
+const ISSUE_ENTITY_TYPE = 'issue';
+const CONTEXT_EVENT_ORIGIN = 'cli';
+// Tier-2 agnostic freshness floor: a stale-but-loaded issue re-blocks after this
+// window; one `forge recap` clears it. Overridable via
+// `workflow.gates.gate.read_first.window` at the call site (P2).
+const DEFAULT_WINDOW_MS = 24 * 60 * 60 * 1000;
+
+// Kernel lifecycle (resolve + close-what-you-built) is shared with gate-events
+// via lib/kernel/owned-kernel; `resolveOwnedKernel`/`closeIfOwned` are imported.
+
+/** Coarse window bucket for a timestamp — the roll-over that makes re-reads fresh. */
+function windowBucket(nowMs, windowMs) {
+  return Math.floor(nowMs / windowMs);
+}
+
+/**
+ * Idempotency key for a context.loaded event. Scoped to issue + scope
+ * (session id when present, else actor) + window bucket so a re-read inside the
+ * window is idempotent, while the next window mints a fresh event.
+ */
+function contextLoadedIdempotencyKey(issueId, scope, bucket) {
+  return `${CONTEXT_LOADED_EVENT}:${issueId}:${scope}:${bucket}`;
+}
+
+/** Shape a stored kernel_events row into the context-event view callers consume. */
+function parseContextEvent(row) {
+  let payload;
+  try {
+    payload = row.payload_json ? JSON.parse(row.payload_json) : {};
+  } catch {
+    payload = {};
+  }
+  const view = {
+    event_type: row.event_type,
+    actor: row.actor,
+    created_at: row.created_at,
+  };
+  if (payload.session !== undefined) view.session = payload.session;
+  if (payload.cmd !== undefined) view.cmd = payload.cmd;
+  if (payload.budget !== undefined) view.budget = payload.budget;
+  return view;
+}
+
+function isIdempotencyRace(error) {
+  const message = error && error.message ? String(error.message) : '';
+  return /UNIQUE constraint failed/i.test(message) && /idempotency_key/i.test(message);
+}
+
+/**
+ * Record that an issue's context was loaded. Idempotent per issue+scope+window.
+ * Validates the issue exists (no orphan events).
+ *
+ * @param {string} projectRoot
+ * @param {Object} params
+ * @param {string} params.issueId
+ * @param {string} [params.cmd] - the command that loaded the context (recap|show).
+ * @param {string} [params.session] - harness session id (Tier-1 scoping) when known.
+ * @param {number|string} [params.budget]
+ * @param {Object} [params.env] - env source for actor resolution.
+ * @param {Object} [params.deps] - injected { kernelBroker, kernelDriver }.
+ * @param {string} [params.now] - ISO timestamp (defaults to now).
+ * @param {number} [params.windowMs] - freshness window (defaults to 24h).
+ * @returns {Promise<{ ok: boolean, duplicate?: boolean, issueMissing?: boolean, event?: Object, actor?: string }>}
+ */
+async function recordContextLoaded(projectRoot, params = {}) {
+  const { issueId, cmd, session, budget, env, deps, now, windowMs } = params;
+  const actor = resolveIssueActor(env || process.env) || 'forge';
+  const kernel = await resolveOwnedKernel(projectRoot, deps);
+  const { driver, config } = kernel;
+
+  try {
+    const entity = await driver.loadKernelEntity(ISSUE_ENTITY_TYPE, issueId, {}, config);
+    if (!entity) {
+      return { ok: false, issueMissing: true, actor };
+    }
+
+    const nowIso = now || new Date().toISOString();
+    const win = Number.isFinite(windowMs) ? windowMs : DEFAULT_WINDOW_MS;
+    const bucket = windowBucket(Date.parse(nowIso), win);
+    const scope = session || actor;
+    const idempotencyKey = contextLoadedIdempotencyKey(issueId, scope, bucket);
+
+    const existing = await driver.loadKernelEventByIdempotencyKey(idempotencyKey, {}, config);
+    if (existing) {
+      return { ok: true, duplicate: true, event: parseContextEvent(existing), actor };
+    }
+
+    const payload = { actor };
+    if (typeof session === 'string' && session.length > 0) payload.session = session;
+    if (typeof cmd === 'string' && cmd.length > 0) payload.cmd = cmd;
+    if (budget !== undefined) payload.budget = budget;
+
+    const event = {
+      entity_type: ISSUE_ENTITY_TYPE,
+      entity_id: issueId,
+      event_type: CONTEXT_LOADED_EVENT,
+      idempotency_key: idempotencyKey,
+      expected_revision: 0,
+      actor,
+      origin: CONTEXT_EVENT_ORIGIN,
+      payload,
+      created_at: nowIso,
+    };
+
+    try {
+      const inserted = await driver.insertKernelEvent(event, {}, config);
+      return { ok: true, duplicate: false, event: parseContextEvent(inserted), actor };
+    } catch (error) {
+      if (isIdempotencyRace(error)) {
+        const winner = await driver.loadKernelEventByIdempotencyKey(idempotencyKey, {}, config);
+        return { ok: true, duplicate: true, event: winner ? parseContextEvent(winner) : parseContextEvent(event), actor };
+      }
+      throw error;
+    }
+  } finally {
+    closeIfOwned(kernel);
+  }
+}
+
+/**
+ * List every context.loaded event on an issue, oldest first.
+ *
+ * @returns {Promise<Array<{ event_type: string, actor: string, created_at: string, session?: string, cmd?: string }>>}
+ */
+async function listContextLoadedEvents(projectRoot, issueId, options = {}) {
+  const kernel = await resolveOwnedKernel(projectRoot, options.deps);
+  try {
+    const rows = await kernel.driver.listKernelEvents(ISSUE_ENTITY_TYPE, issueId, {}, kernel.config);
+    return (rows || [])
+      .filter(row => row.event_type === CONTEXT_LOADED_EVENT)
+      .map(parseContextEvent);
+  } finally {
+    closeIfOwned(kernel);
+  }
+}
+
+/**
+ * True iff the issue has a context.loaded event that satisfies scoping:
+ * - Tier-1 (session given): an event stamped with the SAME session.
+ * - Tier-2 (no session): an event newer than the freshness window.
+ *
+ * @param {string} projectRoot
+ * @param {string} issueId
+ * @param {{ session?: string, windowMs?: number, now?: string, deps?: Object }} [options]
+ * @returns {Promise<boolean>}
+ */
+async function hasFreshContextLoaded(projectRoot, issueId, options = {}) {
+  const { session, windowMs, now, deps } = options;
+  const events = await listContextLoadedEvents(projectRoot, issueId, { deps });
+  return eventsSatisfyFreshness(events, { session, windowMs, now });
+}
+
+/** Shared freshness predicate over an already-listed event set. */
+function eventsSatisfyFreshness(events, { session, windowMs, now } = {}) {
+  if (!events || events.length === 0) return false;
+  if (typeof session === 'string' && session.length > 0) {
+    return events.some(event => event.session === session);
+  }
+  const nowMs = now ? Date.parse(now) : Date.now();
+  const win = Number.isFinite(windowMs) ? windowMs : DEFAULT_WINDOW_MS;
+  return events.some(event => {
+    const ts = Date.parse(event.created_at);
+    return Number.isFinite(ts) && (nowMs - ts) <= win;
+  });
+}
+
+/**
+ * The gate.read_first verdict for an issue, resolving the kernel ONCE:
+ * - 'missing': the issue does not exist in the consulted kernel. The gate is
+ *   INERT — grounding a phantom issue is meaningless and the real claim will
+ *   fail on its own; this is also what keeps unit doubles (fake runner, no real
+ *   store) from being false-blocked. No bypass for a REAL issue: a claim on a
+ *   non-existent issue fails regardless.
+ * - 'loaded': a context.loaded event satisfies session/window scoping -> allow.
+ * - 'unread': the issue exists but has no fresh context.loaded event -> BLOCK.
+ *
+ * @returns {Promise<'missing'|'loaded'|'unread'>}
+ */
+async function readFirstVerdict(projectRoot, issueId, options = {}) {
+  const { session, windowMs, now, deps } = options;
+  const kernel = await resolveOwnedKernel(projectRoot, deps);
+  const { driver, config } = kernel;
+  try {
+    const entity = await driver.loadKernelEntity(ISSUE_ENTITY_TYPE, issueId, {}, config);
+    if (!entity) return 'missing';
+    const rows = await driver.listKernelEvents(ISSUE_ENTITY_TYPE, issueId, {}, config);
+    const events = (rows || []).filter(row => row.event_type === CONTEXT_LOADED_EVENT).map(parseContextEvent);
+    return eventsSatisfyFreshness(events, { session, windowMs, now }) ? 'loaded' : 'unread';
+  } finally {
+    closeIfOwned(kernel);
+  }
+}
+
+module.exports = {
+  CONTEXT_LOADED_EVENT,
+  DEFAULT_WINDOW_MS,
+  contextLoadedIdempotencyKey,
+  parseContextEvent,
+  recordContextLoaded,
+  listContextLoadedEvents,
+  hasFreshContextLoaded,
+  readFirstVerdict,
+};

package/lib/grounding/read-first.js

@@ -0,0 +1,112 @@
+'use strict';
+
+/**
+ * @module grounding/read-first
+ *
+ * gate.read_first — the first gate that DENIES (fd4c03b3's first real payment):
+ * acting on an issue requires having read it. Consulted at the `forge claim`
+ * chokepoint (P1) exactly like gate.issue_verify is consulted at the _issue.js
+ * boundary (isIssueVerifyEnabled). Fail-closed: no context.loaded event for the
+ * issue this session/window -> a block result whose remedy IS the load action
+ * (`forge recap <id>`), so the cheapest path through the gate is the correct
+ * behavior. Disabling rail.grounding (master) or gate.read_first allows the
+ * action (logged), same toggle surface as rail.kernel_tracking.
+ */
+
+const { getResolvedRuntimeGraph } = require('../core/runtime-graph');
+const { readFirstVerdict } = require('./context-events');
+
+const GROUNDING_RAIL_ID = 'rail.grounding';
+const READ_FIRST_GATE_ID = 'gate.read_first';
+
+/**
+ * The block message. Contract: exit != 0, remedy is one copy-pastable command,
+ * and running that command both satisfies the gate AND injects the context.
+ */
+function buildReadFirstBlockMessage(issueId) {
+  return [
+    `✗ ${READ_FIRST_GATE_ID}: issue ${issueId} has not been read this session.`,
+    `  Run: forge recap ${issueId} first`,
+    `  Then retry. (Override: forge gate disable ${READ_FIRST_GATE_ID} — logged.)`,
+  ].join('\n');
+}
+
+/**
+ * Resolve whether grounding + read_first are BOTH enabled. Mirrors
+ * isIssueVerifyEnabled: an injected opts.resolveRuntimeGraph wins (tests); an
+ * unresolvable config (lint errors) yields `unknown` so the caller can fail-open
+ * on a broken config rather than bricking claim.
+ *
+ * @returns {{ enabled: boolean, disabledPrimitive?: string, unknown?: boolean }}
+ */
+function resolveReadFirstEnabled(projectRoot, opts = {}) {
+  const resolveGraph = opts.resolveRuntimeGraph || getResolvedRuntimeGraph;
+  let graph;
+  try {
+    graph = resolveGraph({ projectRoot });
+  } catch {
+    return { enabled: false, unknown: true };
+  }
+  const rail = (graph.rails || []).find(candidate => candidate.id === GROUNDING_RAIL_ID);
+  const gate = (graph.gates || []).find(candidate => candidate.id === READ_FIRST_GATE_ID);
+  const railOn = rail ? rail.enabled !== false : true;
+  const gateOn = gate ? gate.enabled !== false : true;
+  if (!railOn) return { enabled: false, disabledPrimitive: GROUNDING_RAIL_ID };
+  if (!gateOn) return { enabled: false, disabledPrimitive: READ_FIRST_GATE_ID };
+  return { enabled: true };
+}
+
+/**
+ * Consult gate.read_first for an issue. Returns `null` when the action is
+ * allowed (gate off, or a fresh context.loaded event exists), or a block result
+ * `{ success:false, error, exitCode }` when the issue has not been read.
+ *
+ * @param {string} projectRoot
+ * @param {string} issueId
+ * @param {Object} [opts] - { resolveRuntimeGraph, kernelBroker, kernelDriver, session, windowMs, now }
+ * @returns {Promise<null | { success: false, error: string, exitCode: number }>}
+ */
+async function checkReadFirst(projectRoot, issueId, opts = {}) {
+  const state = resolveReadFirstEnabled(projectRoot, opts);
+  if (!state.enabled) {
+    // Disabled (or unresolvable config) -> allow. Log the deliberate skip.
+    if (state.disabledPrimitive) {
+      console.error(`forge: ${state.disabledPrimitive} disabled — claim on ${issueId} allowed without grounding check.`);
+    }
+    return null;
+  }
+
+  const deps = (opts.kernelBroker && opts.kernelDriver)
+    ? { kernelBroker: opts.kernelBroker, kernelDriver: opts.kernelDriver }
+    : undefined;
+
+  let verdict;
+  try {
+    verdict = await readFirstVerdict(projectRoot, issueId, {
+      session: opts.session,
+      windowMs: opts.windowMs,
+      now: opts.now,
+      deps,
+    });
+  } catch {
+    // Kernel unavailable (broken env) -> fail-open, like issue_verify on a
+    // config error. In production the project kernel resolves; the enforced
+    // path is the normal one.
+    return null;
+  }
+
+  // 'missing' -> the issue is not in the consulted kernel; the gate is inert (a
+  // real claim on a non-existent issue fails on its own — no grounding bypass).
+  // 'loaded' -> a fresh context.loaded event exists. Both allow.
+  if (verdict !== 'unread') return null;
+
+  return { success: false, error: buildReadFirstBlockMessage(issueId), exitCode: 6 };
+}
+
+module.exports = {
+  GROUNDING_RAIL_ID,
+  READ_FIRST_GATE_ID,
+  buildReadFirstBlockMessage,
+  resolveReadFirstEnabled,
+  checkReadFirst,
+};

package/lib/harness-capability-matrix.js

@@ -33,7 +33,7 @@ const SOURCE_ROWS = [
   ['S4', 'Cursor MCP', 'https://docs.cursor.com/context/model-context-protocol', 'Cursor connects external tools and data sources through MCP using stdio, SSE, and streamable HTTP transports.'],
   ['S5', 'Codex skills', 'https://developers.openai.com/codex/skills', 'Codex skills package instructions, resources, and scripts; Codex scans .agents/skills from cwd up to the repo root for repo-scope discovery. Forge installs the global $CODEX_HOME/skills from the canonical skills/ source AND commits the repo-local .agents/skills mirror (kept in sync with skills/ by a pre-commit hook + drift gate) for teammate-clone discovery.'],
   ['S6', 'Codex MCP', 'https://developers.openai.com/codex/mcp', 'Codex configures MCP servers in config.toml and supports plugin-provided MCP servers.'],
-  ['S7', 'Codex hooks', 'https://developers.openai.com/codex/hooks', 'Codex hooks run deterministic scripts during lifecycle events.'],
+  ['S7', 'Codex hooks', 'https://developers.openai.com/codex/hooks', 'Codex hooks run deterministic scripts during lifecycle events; they live in GLOBAL $CODEX_HOME/config.toml so project setup does not render them. Codex instead reads the committed project-local AGENTS.md every session, which is the always-on carrier for Forge instruction/policy including the using-forge skill-dispatch pointer (see S9).'],
   ['S8', 'Codex plugins and marketplaces', 'https://developers.openai.com/codex/plugins/build', 'Codex plugins can package skills, apps, MCP servers, hooks, and marketplace metadata.'],
   ['S9', 'AGENTS.md standard', 'https://agents.md/', 'AGENTS.md provides repository instructions for coding agents.'],
   ['S10', 'Cursor Agent Skills', 'https://docs.cursor.com/en/agent/skills', 'Cursor reads on-demand Agent Skills from .cursor/skills/<name>/SKILL.md; Forge populates them at setup from the canonical skills/ source.'],
@@ -41,7 +41,7 @@ const SOURCE_ROWS = [
   ['S12', 'Cursor ignore files', 'https://cursor.com/docs/reference/ignore-file', 'Cursor reads project-local .cursorignore (blocks AI access + indexing) and .cursorindexingignore (index-only), gitignore-style; .gitignore and common secret/lock files are ignored by default.'],
   ['S13', 'Codex sandbox and approvals config', 'https://developers.openai.com/codex/config-reference', 'Codex config.toml sets sandbox_mode (read-only/workspace-write/danger-full-access) and approval_policy (untrusted/on-request/never); a project-local .codex/config.toml is honored ONLY when the project is trusted in the GLOBAL $CODEX_HOME/config.toml (projects.<path>.trust_level).'],
   ['S14', 'Claude Code hooks', 'https://code.claude.com/docs/en/hooks', 'Claude Code hooks live in .claude/settings.json under a `hooks` block; a PreToolUse matcher group (e.g. "Write|Edit"/"Bash") runs a command that can deny the tool call via hookSpecificOutput.permissionDecision.'],
-  ['S15', 'Cursor hooks', 'https://cursor.com/docs/hooks', 'Cursor 1.7+ reads project-local .cursor/hooks.json ({ version: 1, hooks }); only before* events (beforeShellExecution/beforeReadFile/beforeMCPExecution) can deny — there is no pre-edit deny event, so afterFileEdit is observational.'],
+  ['S15', 'Cursor hooks', 'https://cursor.com/docs/hooks', 'Cursor 1.7+ reads project-local .cursor/hooks.json ({ version: 1, hooks }); only before* events (beforeShellExecution/beforeReadFile/beforeMCPExecution) can deny — there is no pre-edit deny event, so afterFileEdit is observational. Cursor hooks are therefore NOT the session-context path: Cursor auto-injects always-apply .cursor/rules/*.mdc (alwaysApply:true) every session (see S3), which is the always-on carrier for the using-forge skill-dispatch pointer.'],
   ['S16', 'Hermes Agent event hooks', 'https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks/', 'Hermes (NousResearch) shell hooks are declared in a `hooks:` block in the GLOBAL ~/.hermes/config.yaml; each matcher/command entry runs as a subprocess over a JSON-stdin/stdout wire protocol, and a pre_tool_call hook CAN deny a tool call ({action:block, message} — it also accepts the Claude-Code {decision:block, reason} shape).'],
 ];
 

package/lib/hook-renderer.js

@@ -75,17 +75,52 @@ const FORGE_CONTEXT_MARKER = 'hooks session-start';
 // re-merge recognizes + replaces the Forge-owned UserPromptSubmit entry in place, exactly
 // as FORGE_CONTEXT_MARKER does for the SessionStart entry.
 const FORGE_INBOX_CONTEXT_MARKER = 'hooks inbox-pickup';
-
-// Per-harness SessionStart context-injection capability. Honest capability matrix —
-// only Claude exposes a native session-start surface that can inject additionalContext.
-// Cursor's 1.7 hooks are deny-oriented (no session-start context surface); Codex and
-// Hermes hooks live in GLOBAL home config that project setup never writes. We NEVER
-// fake parity: each non-Claude harness carries an explicit, tested skip reason.
+// The PR-shepherd events context hook (a SECOND UserPromptSubmit-tier hook). Its own
+// marker so a re-merge recognizes + replaces the Forge-owned entry in place. The whole
+// Forge UserPromptSubmit group is already recognized via the inbox marker, but this keeps
+// the shepherd-events command independently identifiable (symmetry with the other tiers).
+const FORGE_SHEPHERD_EVENTS_MARKER = 'hooks shepherd-events';
+// The memory-recall context hook (UserPromptSubmit tier). Its own idempotency marker so a
+// re-render recognizes and REPLACES the Forge-owned entry in place rather than duplicating it.
+const FORGE_MEMORY_RECALL_MARKER = 'hooks memory-recall';
+// The capture-on-exit context hook (PreCompact + Stop tier). A THIRD context marker so a
+// re-merge recognizes + replaces the Forge-owned PreCompact/Stop entries in place. Both
+// events share this one marker (they differ only by a --trigger suffix on the command).
+//
+// It matches the FULL resolved Forge invocation (`node "<abs bin/forge.js>" hooks capture`),
+// NOT the bare `hooks capture` verb: a bare-substring check would treat ANY user hook command
+// that merely mentions "hooks capture" as Forge-owned and DELETE it on re-merge (data-integrity
+// bug, CodeRabbit on #397). Only Forge's own rendered capture command contains this prefix, so
+// the merge replaces exactly Forge's group and preserves the user's.
+const FORGE_CAPTURE_CONTEXT_MARKER = `${FORGE_CLI} hooks capture`;
+
+// Per-harness SessionStart HOOK-render capability. This constant governs ONE thing: whether
+// Forge renders a harness-native SessionStart *hook* that injects additionalContext. Only Claude
+// exposes that surface, so only Claude is rendered:true. Every other harness is rendered:false
+// with an HONEST reason naming WHERE the same dispatch bootstrap is delivered instead — because
+// the bootstrap is NOT Claude-only, it just travels a different always-on surface per harness
+// (see BOOTSTRAP_DELIVERY below): Cursor auto-applies an always-on rule (.cursor/rules/*.mdc,
+// alwaysApply:true); Codex reads the committed project-local AGENTS.md every session; Hermes
+// consumes it through the forge CLI (forge prime/orient + forge skill for). We NEVER fake parity
+// and NEVER branch on harness identity at runtime — delivery is keyed by SURFACE TYPE.
 const SESSION_START_SUPPORT = Object.freeze({
   claude: Object.freeze({ rendered: true }),
-  cursor: Object.freeze({ rendered: false, reason: 'no-session-start-surface' }),
-  codex: Object.freeze({ rendered: false, reason: 'global-config' }),
-  hermes: Object.freeze({ rendered: false, reason: 'global-config' }),
+  cursor: Object.freeze({ rendered: false, reason: 'delivered-via-rule-surface' }),
+  codex: Object.freeze({ rendered: false, reason: 'delivered-via-agents-md' }),
+  hermes: Object.freeze({ rendered: false, reason: 'delivered-via-cli-fallback' }),
+});
+
+// Where the using-forge dispatch BOOTSTRAP reaches each harness EVERY session. Data, not
+// identity-branching: the parity gate iterates this so no harness is silently left with no
+// auto-surface. Only Claude's is a native SessionStart hook; the rest are equally always-on
+// surfaces (a Cursor always-apply rule, the committed AGENTS.md for Codex, the forge CLI as an
+// honest fallback for Hermes). All four ALSO carry the full using-forge SKILL.md via the synced
+// skill mirrors. 'cli-fallback' is the explicit honest-fallback marker (no faked native surface).
+const BOOTSTRAP_DELIVERY = Object.freeze({
+  claude: 'session-start-hook',
+  cursor: 'always-apply-rule',
+  codex: 'agents-md',
+  hermes: 'cli-fallback',
 });
 
 // Per-harness UserPromptSubmit context-injection capability (the near-real-time inbox
@@ -99,6 +134,18 @@ const USER_PROMPT_SUBMIT_SUPPORT = Object.freeze({
   hermes: Object.freeze({ rendered: false, reason: 'global-config' }),
 });
 
+// Per-harness session-END (capture-on-exit) capability. Only Claude exposes native
+// PreCompact + Stop hook surfaces where Forge can snapshot session learnings BEFORE
+// context is compacted or the session ends. Cursor 1.7 hooks are deny-oriented with no
+// session-end surface; Codex and Hermes hooks live in GLOBAL home config project setup
+// never writes. Same honesty rule as the other context tiers — no faked parity.
+const SESSION_END_SUPPORT = Object.freeze({
+  claude: Object.freeze({ rendered: true }),
+  cursor: Object.freeze({ rendered: false, reason: 'no-session-end-surface' }),
+  codex: Object.freeze({ rendered: false, reason: 'global-config' }),
+  hermes: Object.freeze({ rendered: false, reason: 'global-config' }),
+});
+
 // Claude exposes $CLAUDE_PROJECT_DIR (absolute project root) to hook commands and
 // documents it as THE cwd-independent way to reference project-local hook scripts —
 // a bare relative path breaks whenever Claude runs the hook from another cwd. Cursor
@@ -114,7 +161,7 @@ function adapterInvocation(harness) {
  * (per-commit) so the rendered Claude PreToolUse groups read write-guard first.
  */
 const FORGE_HOOK_CONTRACT = Object.freeze({
-  schemaVersion: '1.1.0',
+  schemaVersion: '1.2.0',
   kind: 'forge.hookContract',
   adapter: FORGE_HOOK_ADAPTER,
   intents: Object.freeze([
@@ -152,6 +199,51 @@ const FORGE_HOOK_CONTRACT = Object.freeze({
       lifecycle: 'user-prompt-submit',
       command: `${FORGE_CLI} hooks inbox-pickup`,
     }),
+    Object.freeze({
+      id: 'memory-recall',
+      kind: 'context',
+      cliAction: 'memory-recall',
+      // QUERY-RELEVANT MEMORY (tier-2): on each prompt, ranks stored memories by BM25
+      // relevance to the submitted prompt (read from the hook's own stdin) and injects the
+      // survivors, gated by a relevance floor + anaphora guard + cross-turn dedupe + a hard
+      // token budget. Complements the recency digest at SessionStart, which answers a
+      // different question (what's newest, not what's relevant to THIS turn). Reads the
+      // user's OWN kernel memory via a supported hook and its own stdin input — it NEVER
+      // injects into a running session's stdin and never drives the agent (Anthropic Usage
+      // Policy). Kill-switch: `forge gate disable rail.memory_recall`.
+      enforces: 'Memory recall: on each UserPromptSubmit, inject query-relevant stored memories ranked by BM25 against the submitted prompt, gated by a relevance floor, an anaphora guard, cross-turn dedupe, and a hard token budget (compact to avoid additionalContext accumulation). Additive and FAIL-OPEN — nothing relevant, a disabled rail, or any error injects nothing and never blocks a prompt.',
+      lifecycle: 'user-prompt-submit',
+      command: `${FORGE_CLI} hooks memory-recall`,
+    }),
+    Object.freeze({
+      id: 'shepherd-events',
+      kind: 'context',
+      cliAction: 'shepherd-events',
+      // PR-SHEPHERD DELTAS: surfaces a compact, capped digest of NEW PR-monitor events
+      // (verdict changes, failed checks, new threads, merged/closed) since the last read,
+      // then advances the per-PR consumer cursor. This is the CONSUMER side of the constant
+      // watcher — the watch loop writes the journal, this pushes the deltas each turn. Reads
+      // the user's OWN local journal via a supported hook — NEVER stdin injection, never
+      // drives the agent (Anthropic Usage Policy).
+      enforces: 'PR shepherd events: on each UserPromptSubmit, surface a compact, capped digest of NEW PR-monitor events (verdict changes, failed checks, new threads, merged/closed) since the last read across open-PR journals, then advance the cursor. Compact to avoid additionalContext accumulation. Additive and FAIL-OPEN — a missing digest never blocks a prompt.',
+      lifecycle: 'user-prompt-submit',
+      command: `${FORGE_CLI} hooks shepherd-events`,
+    }),
+    Object.freeze({
+      id: 'memory-capture',
+      kind: 'context',
+      cliAction: 'capture',
+      // CAPTURE-ON-EXIT: the write half of Forge memory. SessionStart INJECTS remembered
+      // notes but nothing ever CAPTURES on the way out, so long sessions lose learnings and
+      // memory stays orphaned (the eval scored memory pull-only). PreCompact + Stop fire this
+      // to snapshot a bounded session-summary note BEFORE context is compacted / the session
+      // ends. Persists to the memory store — it NEVER injects into the turn and never drives
+      // the agent (Anthropic Usage Policy). The trigger (precompact|stop) rides as a --trigger
+      // suffix stamped by the rendered hook, so the CLI never has to read hook stdin.
+      enforces: 'Capture-on-exit: snapshot a bounded session-summary note (trigger + in-progress issues) into the memory store on PreCompact and Stop, BEFORE context is compacted or the session ends. Additive and FAIL-OPEN — a capture failure never blocks a session.',
+      lifecycle: 'session-end',
+      command: `${FORGE_CLI} hooks capture`,
+    }),
   ]),
 });
 
@@ -202,6 +294,16 @@ function userPromptSubmitCapability(harness) {
   return USER_PROMPT_SUBMIT_SUPPORT[harness] || { rendered: false, reason: 'unknown-harness' };
 }
 
+/**
+ * Report the per-harness session-END (capture-on-exit) capability (the honest matrix for
+ * the PreCompact + Stop capture tier).
+ * @param {string} harness
+ * @returns {{ rendered: boolean, reason?: string }}
+ */
+function sessionEndCapability(harness) {
+  return SESSION_END_SUPPORT[harness] || { rendered: false, reason: 'unknown-harness' };
+}
+
 /**
  * Render the Claude `.claude/settings.json` `hooks` block (PreToolUse groups only).
  * Write/Edit/MultiEdit/NotebookEdit → protected-path deny; Bash → TDD gate.
@@ -229,8 +331,30 @@ function renderClaudeHooks(contract) {
     // Surfaces pending targeted dashboard instruction comments (fenced kernel DATA) on each
     // prompt; the command emits { hookSpecificOutput.additionalContext }. Reads the user's
     // own kernel data via a supported hook — NEVER stdin injection (Anthropic Usage Policy).
+    // The UserPromptSubmit context hooks share ONE Forge-owned group (inbox-pickup nudge,
+    // PR-shepherd deltas, and query-relevant memory recall). Claude runs every hook in the
+    // group and appends each hook's additionalContext; keeping them in one group means a
+    // re-merge replaces the set atomically (the group is Forge-owned via any of their
+    // markers). All three are compact + fail-open. (memory-recall reads its own hook stdin
+    // for the prompt — that is its supported input, not session-stdin injection.)
     UserPromptSubmit: [
-      { hooks: [{ type: 'command', command: harnessCommand(contract, 'inbox-pickup', 'claude') }] },
+      {
+        hooks: [
+          { type: 'command', command: harnessCommand(contract, 'inbox-pickup', 'claude') },
+          { type: 'command', command: harnessCommand(contract, 'shepherd-events', 'claude') },
+          { type: 'command', command: harnessCommand(contract, 'memory-recall', 'claude') },
+        ],
+      },
+    ],
+    // Capture-on-exit (memory capture). PreCompact fires before context is compacted; Stop
+    // fires when the agent finishes. Both call the same capture command; the event stamps the
+    // --trigger so the CLI never reads hook stdin. The command persists a bounded session
+    // summary — it emits NO stdout (a Stop hook that printed text would inject into the turn).
+    PreCompact: [
+      { hooks: [{ type: 'command', command: `${harnessCommand(contract, 'memory-capture', 'claude')} --trigger precompact` }] },
+    ],
+    Stop: [
+      { hooks: [{ type: 'command', command: `${harnessCommand(contract, 'memory-capture', 'claude')} --trigger stop` }] },
     ],
   };
 }
@@ -311,7 +435,10 @@ function isForgeCommand(command) {
   return typeof command === 'string'
     && (command.includes(FORGE_HOOK_MARKER)
       || command.includes(FORGE_CONTEXT_MARKER)
-      || command.includes(FORGE_INBOX_CONTEXT_MARKER));
+      || command.includes(FORGE_INBOX_CONTEXT_MARKER)
+      || command.includes(FORGE_SHEPHERD_EVENTS_MARKER)
+      || command.includes(FORGE_MEMORY_RECALL_MARKER)
+      || command.includes(FORGE_CAPTURE_CONTEXT_MARKER));
 }
 
 /** True when a hook group/entry is Forge-owned (any inner command is Forge-owned). */
@@ -436,10 +563,15 @@ module.exports = {
   FORGE_HOOK_MARKER,
   FORGE_CONTEXT_MARKER,
   FORGE_INBOX_CONTEXT_MARKER,
+  FORGE_MEMORY_RECALL_MARKER,
+  FORGE_CAPTURE_CONTEXT_MARKER,
   SESSION_START_SUPPORT,
+  BOOTSTRAP_DELIVERY,
   USER_PROMPT_SUBMIT_SUPPORT,
+  SESSION_END_SUPPORT,
   sessionStartCapability,
   userPromptSubmitCapability,
+  sessionEndCapability,
   HookConfigParseError,
   renderClaudeHooks,
   renderCursorHooks,