forge-workflow 0.1.0-beta.5 → 0.1.0-beta.6

package/lib/gate-events.js

@@ -49,8 +49,13 @@ const GATE_EVENT_ORIGIN = 'cli';
  * SAME-actor re-approval mints no duplicate, while a later reject (different
  * decision) or a different actor is recorded as its own event.
  */
-function gateIdempotencyKey(eventType, issueId, gateId, actor) {
-  return `${eventType}:${issueId}:${gateId}:${actor}`;
+function gateIdempotencyKey(eventType, issueId, gateId, actor, expiresAt) {
+  const base = `${eventType}:${issueId}:${gateId}:${actor}`;
+  return expiresAt ? `${base}:${expiresAt}` : base;
+}
+
+function gateControlId(issueId, gateId) {
+  return `gate:${issueId}:${gateId}`;
 }
 
 /** Shape a stored kernel_events row into the gate-event view callers consume. */
@@ -67,6 +72,18 @@ function parseGateEvent(row) {
     actor: row.actor,
     created_at: row.created_at,
   };
+  // Older direct callers supplied only the legacy row subset and consumed its
+  // exact four-field view. Stored Kernel rows always carry entity_id, so enrich
+  // those audit/status views without changing that legacy parse contract.
+  if (row.entity_id) {
+    view.issue_id = row.entity_id;
+    view.control_id = payload.control_id || gateControlId(row.entity_id, payload.gate);
+    view.decision = row.event_type === GATE_APPROVED_EVENT ? 'approved' : 'rejected';
+    view.issued_at = row.created_at;
+    view.expires_at = payload.expires_at ?? null;
+    view.request_identity = payload.request_identity ?? null;
+    view.generation = Number.isInteger(payload.generation) ? payload.generation : 0;
+  }
   if (payload.reason !== undefined) view.reason = payload.reason;
   return view;
 }
@@ -76,10 +93,43 @@ function isIdempotencyRace(error) {
   return /UNIQUE constraint failed/i.test(message) && /idempotency_key/i.test(message);
 }
 
+function isActiveApproval(event, now) {
+  if (!event || event.event_type !== GATE_APPROVED_EVENT) return false;
+  if (!event.expires_at) return true;
+  const nowMillis = Date.parse(now);
+  const expiryMillis = Date.parse(event.expires_at);
+  return Number.isFinite(nowMillis) && Number.isFinite(expiryMillis) && nowMillis < expiryMillis;
+}
+
+function planGateGeneration(events, params) {
+  const { gateId, decision, actor, requestIdentity, now } = params;
+  const gateEvents = events.filter(event => event.gate === gateId);
+  const latest = gateEvents.at(-1);
+  const maxGeneration = gateEvents.reduce(
+    (max, event) => Math.max(max, Number.isInteger(event.generation) ? event.generation : 0),
+    -1,
+  );
+
+  if (decision === 'approved') {
+    const identicalActive = latest
+      && latest.actor === actor
+      && latest.request_identity === requestIdentity
+      && isActiveApproval(latest, now);
+    if (identicalActive) return { duplicateEvent: latest, generation: latest.generation };
+    return { duplicateEvent: null, generation: maxGeneration + 1 };
+  }
+
+  if (latest?.event_type === GATE_REJECTED_EVENT && latest.actor === actor) {
+    return { duplicateEvent: latest, generation: latest.generation };
+  }
+  return { duplicateEvent: null, generation: Math.max(maxGeneration, 0) };
+}
+
 /**
- * Record a gate decision as a kernel event on the issue. Idempotent per
- * issue+gate+actor+decision. Validates the issue exists (the caller validates the
- * gate id against the known-gate set before calling).
+ * Record a gate decision as a kernel event on the issue. Active identical
+ * requests are idempotent; expiry/rejection advances the durable generation so
+ * a later approval can become authoritative. Validates the issue exists (the
+ * caller validates the gate id against the known-gate set before calling).
  *
  * @param {string} projectRoot
  * @param {Object} params
@@ -93,7 +143,7 @@ function isIdempotencyRace(error) {
  * @returns {Promise<{ ok: boolean, duplicate?: boolean, issueMissing?: boolean, event?: Object, actor?: string }>}
  */
 async function recordGateEvent(projectRoot, params = {}) {
-  const { issueId, gateId, decision, reason, env, deps, now } = params;
+  const { issueId, gateId, decision, reason, expiresAt, requestIdentity, env, deps, now } = params;
   const eventType = GATE_EVENT_TYPES[decision];
   if (!eventType) {
     throw new Error(`Unknown gate decision '${decision}' (expected 'approved' or 'rejected').`);
@@ -109,14 +159,42 @@ async function recordGateEvent(projectRoot, params = {}) {
       return { ok: false, issueMissing: true, actor };
     }
 
-    const idempotencyKey = gateIdempotencyKey(eventType, issueId, gateId, actor);
+    const createdAt = now || new Date().toISOString();
+    const stableRequestIdentity = requestIdentity ?? expiresAt ?? null;
+    const rows = await driver.listKernelEvents(ISSUE_ENTITY_TYPE, issueId, {}, config);
+    const generationPlan = planGateGeneration((rows || []).map(parseGateEvent), {
+      gateId,
+      decision,
+      actor,
+      requestIdentity: stableRequestIdentity,
+      now: createdAt,
+    });
+    if (generationPlan.duplicateEvent) {
+      return { ok: true, duplicate: true, event: generationPlan.duplicateEvent, actor };
+    }
+    const keyParts = [stableRequestIdentity];
+    if (generationPlan.generation > 0) keyParts.push(`generation=${generationPlan.generation}`);
+    const idempotencyKey = gateIdempotencyKey(
+      eventType,
+      issueId,
+      gateId,
+      actor,
+      keyParts.filter(Boolean).join(':') || undefined,
+    );
 
     const existing = await driver.loadKernelEventByIdempotencyKey(idempotencyKey, {}, config);
     if (existing) {
       return { ok: true, duplicate: true, event: parseGateEvent(existing), actor };
     }
 
-    const payload = { gate: gateId, actor };
+    const payload = {
+      gate: gateId,
+      actor,
+      control_id: gateControlId(issueId, gateId),
+      expires_at: expiresAt ?? null,
+      request_identity: stableRequestIdentity,
+      generation: generationPlan.generation,
+    };
     if (typeof reason === 'string' && reason.length > 0) payload.reason = reason;
 
     const event = {
@@ -128,7 +206,7 @@ async function recordGateEvent(projectRoot, params = {}) {
       actor,
       origin: GATE_EVENT_ORIGIN,
       payload,
-      created_at: now || new Date().toISOString(),
+      created_at: createdAt,
     };
 
     try {
@@ -166,6 +244,12 @@ async function listGateEvents(projectRoot, issueId, options = {}) {
   }
 }
 
+function evaluateGateApproval(events, gateId, now = new Date().toISOString()) {
+  const decisions = events.filter(event => event.gate === gateId);
+  const event = decisions.at(-1);
+  return { approved: isActiveApproval(event, now), event };
+}
+
 /**
  * True iff a `gate.approved` event exists for this issue + gate.
  *
@@ -177,7 +261,7 @@ async function listGateEvents(projectRoot, issueId, options = {}) {
  */
 async function isGateApproved(projectRoot, issueId, gateId, options = {}) {
   const events = await listGateEvents(projectRoot, issueId, options);
-  return events.some(event => event.event_type === GATE_APPROVED_EVENT && event.gate === gateId);
+  return evaluateGateApproval(events, gateId, options.now).approved;
 }
 
 module.exports = {
@@ -185,8 +269,12 @@ module.exports = {
   GATE_REJECTED_EVENT,
   GATE_EVENT_TYPES,
   gateIdempotencyKey,
+  gateControlId,
+  isActiveApproval,
+  planGateGeneration,
   parseGateEvent,
   recordGateEvent,
   listGateEvents,
+  evaluateGateApproval,
   isGateApproved,
 };

package/lib/github-context.js

@@ -0,0 +1,308 @@
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+
+const ACCOUNT_KEY = 'github.account';
+const HOST = 'github.com';
+const LOGIN_RE = /^(?=.{1,39}$)[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/;
+const GITHUB_ENV_NAMES = new Set(['gh_token', 'github_token', 'gh_host', 'gh_repo']);
+const GITHUB_SECRET_ENV_NAMES = new Set(['gh_token', 'github_token']);
+
+class GithubContextError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'GithubContextError';
+    this.code = code;
+  }
+
+  toJSON() {
+    return { code: this.code, message: this.message };
+  }
+}
+
+function validateGithubLogin(login) {
+  return typeof login === 'string' && LOGIN_RE.test(login);
+}
+
+function safeLogin(login) {
+  return validateGithubLogin(login) ? login : null;
+}
+
+function runnerFor(options) {
+  return options.runner || options._runner || options._exec || options.execFileSync || defaultRunner;
+}
+
+function defaultRunner(command, args, options = {}) {
+  return execFileSync(command, args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    windowsHide: true,
+    ...options,
+  });
+}
+
+function errorText(error) {
+  return [error?.message, error?.stderr?.toString?.(), error?.stdout?.toString?.()]
+    .filter(Boolean)
+    .join(' ')
+    .toLowerCase();
+}
+
+function isUnsupportedTokenCapability(error) {
+  const text = errorText(error);
+  return /unknown (?:flag|option)|invalid (?:flag|option)|unexpected argument|does not support/.test(text)
+    && /user|hostname/.test(text);
+}
+
+function safeCommandFailure(code, message) {
+  return new GithubContextError(code, message);
+}
+
+function safeGithubCommandFailure(error) {
+  const text = errorText(error);
+  const failure = safeCommandFailure(
+    'GITHUB_COMMAND_FAILED',
+    /rate limit|secondary rate/.test(text)
+      ? 'The GitHub CLI command was rate limited.'
+      : 'The GitHub CLI command failed without exposing its output.',
+  );
+  const matchedStatus = /\bhttp\s+(401|403|429)\b/.exec(text)?.[1];
+  let httpStatus;
+  if ([401, 403, 429].includes(error?.httpStatus)) httpStatus = error.httpStatus;
+  else if ([401, 403, 429].includes(error?.status)) httpStatus = error.status;
+  else httpStatus = Number(matchedStatus) || undefined;
+  const retryAfter = Number(error?.retryAfter);
+  if (httpStatus) failure.httpStatus = httpStatus;
+  if (Number.isFinite(retryAfter) && retryAfter > 0) failure.retryAfter = retryAfter;
+  return failure;
+}
+
+function gitConfig(projectRoot, args, options, absentIsOkay = false) {
+  try {
+    return runnerFor(options)('git', ['config', '--local', ...args], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+  } catch (error) {
+    if (absentIsOkay && (error?.status === 1 || /key does not contain|not found|no such key/i.test(errorText(error)))) {
+      return '';
+    }
+    throw safeCommandFailure('GIT_CONFIG_FAILED', 'Unable to read this clone-local GitHub account binding.');
+  }
+}
+
+function readGithubAccount(projectRoot, options = {}) {
+  const output = gitConfig(projectRoot, ['--get', ACCOUNT_KEY], options, true);
+  const value = output == null ? '' : output.toString().trim();
+  return value || null;
+}
+
+function writeGithubAccount(projectRoot, login, options = {}) {
+  if (!validateGithubLogin(login)) {
+    throw safeCommandFailure('INVALID_GITHUB_LOGIN', 'GitHub login must be 1-39 letters, numbers, or internal hyphens.');
+  }
+  try {
+    runnerFor(options)('git', ['config', '--local', '--replace-all', ACCOUNT_KEY, login], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+  } catch (_error) {
+    throw safeCommandFailure('GIT_CONFIG_FAILED', 'Unable to write the clone-local GitHub account binding.');
+  }
+}
+
+function unsetGithubAccount(projectRoot, options = {}) {
+  try {
+    runnerFor(options)('git', ['config', '--local', '--unset-all', ACCOUNT_KEY], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+  } catch (error) {
+    if (error?.status === 5 || /key does not contain|not found|no such key/i.test(errorText(error))) return;
+    throw safeCommandFailure('GIT_CONFIG_FAILED', 'Unable to remove the clone-local GitHub account binding.');
+  }
+}
+
+function withoutGithubEnvironment(environment) {
+  const result = {};
+  for (const [key, value] of Object.entries(environment || {})) {
+    if (!GITHUB_ENV_NAMES.has(key.toLowerCase())) result[key] = value;
+  }
+  return result;
+}
+
+function selectedEnvironment(baseEnv, token, additions = {}) {
+  const result = withoutGithubEnvironment(baseEnv);
+  Object.assign(result, withoutGithubEnvironment(additions));
+  result.GH_TOKEN = token;
+  result.GITHUB_TOKEN = token;
+  result.GH_HOST = HOST;
+  return result;
+}
+
+function passthroughEnvironment(baseEnv, additions = {}) {
+  return { ...baseEnv, ...additions };
+}
+
+function retrieveGithubToken(login, options) {
+  if (!validateGithubLogin(login)) {
+    throw safeCommandFailure('INVALID_GITHUB_LOGIN', 'GitHub login must be 1-39 letters, numbers, or internal hyphens.');
+  }
+  const baseEnv = options.baseEnv || options.env || process.env;
+  let output;
+  try {
+    output = runnerFor(options)('gh', ['auth', 'token', '--hostname', HOST, '--user', login], {
+      env: withoutGithubEnvironment(baseEnv),
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+  } catch (error) {
+    if (isUnsupportedTokenCapability(error)) {
+      throw safeCommandFailure('GITHUB_CLI_UNSUPPORTED', 'Upgrade GitHub CLI, then authenticate the account with gh auth login.');
+    }
+    throw safeCommandFailure('GITHUB_NOT_AUTHENTICATED', 'GitHub account is not authenticated; run gh auth login for this account.');
+  }
+
+  const token = output == null ? '' : output.toString().trim();
+  if (!token) {
+    throw safeCommandFailure('GITHUB_NOT_AUTHENTICATED', 'GitHub account is not authenticated; run gh auth login for this account.');
+  }
+  return token;
+}
+
+function loginFromOutput(output) {
+  const text = output == null ? '' : output.toString().trim();
+  if (!text) return null;
+  try {
+    const parsed = JSON.parse(text);
+    return safeLogin(parsed?.login);
+  } catch {
+    // `gh --jq` normally returns plain text; JSON is only a compatibility path.
+    return safeLogin(text.split(/\r?\n/, 1)[0].trim());
+  }
+}
+
+function resolveGithubLogin(token, baseEnv, options) {
+  try {
+    const output = runnerFor(options)('gh', ['api', '--hostname', HOST, 'user', '--jq', '.login'], {
+      env: selectedEnvironment(baseEnv, token),
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+    const login = loginFromOutput(output);
+    if (!login) throw new Error('missing login');
+    return login;
+  } catch {
+    // Provider errors may contain response bodies or credentials; expose only a safe diagnosis.
+    throw safeCommandFailure('GITHUB_AUTH_FAILED', 'Unable to verify the selected GitHub account; run gh auth login and try again.');
+  }
+}
+
+function prepareGithubAccount(_projectRoot, account, options = {}) {
+  if (!validateGithubLogin(account)) {
+    throw safeCommandFailure('INVALID_GITHUB_LOGIN', 'GitHub login must be 1-39 letters, numbers, or internal hyphens.');
+  }
+  const baseEnv = { ...(options.baseEnv || options.env || process.env) };
+  const token = retrieveGithubToken(account, { ...options, baseEnv });
+  const login = resolveGithubLogin(token, baseEnv, options);
+  if (login.toLowerCase() !== account.toLowerCase()) {
+    throw safeCommandFailure('GITHUB_ACCOUNT_MISMATCH', `GitHub account mismatch: expected ${account}, received ${login}.`);
+  }
+  return createPublicContext(publicStatus('ready', account, login), token, baseEnv, options);
+}
+
+function publicStatus(state, account, login) {
+  return Object.freeze({ state, account: account || null, login: login || null });
+}
+
+function createPublicContext(status, token, baseEnv, options) {
+  const context = {
+    status,
+    bound: status.state !== 'unbound',
+    account: status.account,
+    login: status.login,
+  };
+  const secrets = (status.state === 'unbound'
+    ? Object.entries(baseEnv)
+      .filter(([key]) => GITHUB_SECRET_ENV_NAMES.has(key.toLowerCase()))
+      .map(([, value]) => value)
+    : [token])
+    .filter((value) => typeof value === 'string' && value);
+  const environmentForChild = (additions = {}) => status.state === 'unbound'
+    ? passthroughEnvironment(baseEnv, additions)
+    : selectedEnvironment(baseEnv, token, additions);
+  const childRunner = options.childRunner || options._childRunner || runnerFor(options);
+  const runChild = (command, args, runOptions = {}) => {
+    if (typeof command !== 'string' || !Array.isArray(args) || args.some((arg) => typeof arg !== 'string')) {
+      throw safeCommandFailure('INVALID_GH_ARGUMENTS', 'GitHub CLI arguments must be an array of strings.');
+    }
+    try {
+      return childRunner(command, args, {
+        ...runOptions,
+        env: environmentForChild(runOptions.env),
+      });
+    } catch (_error) {
+      throw safeCommandFailure('GITHUB_COMMAND_FAILED', 'The GitHub CLI command failed without exposing its output.');
+    }
+  };
+  const runGh = (args, runOptions = {}) => {
+    if (!Array.isArray(args) || args.some((arg) => typeof arg !== 'string')) {
+      throw safeCommandFailure('INVALID_GH_ARGUMENTS', 'GitHub CLI arguments must be an array of strings.');
+    }
+    try {
+      const output = runnerFor(options)('gh', args, {
+        ...runOptions,
+        env: environmentForChild(runOptions.env),
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+      });
+      return redactTokens(output, secrets);
+    } catch (error) {
+      throw safeGithubCommandFailure(error);
+    }
+  };
+  Object.defineProperties(context, {
+    runChild: { value: runChild, enumerable: false },
+    runGh: { value: runGh, enumerable: false },
+    getStatus: { value: () => ({ ...status }), enumerable: false },
+  });
+  return context;
+}
+
+function redactTokens(value, tokens) {
+  if (value == null) return value;
+  return tokens.slice().sort((left, right) => right.length - left.length)
+    .reduce((redacted, token) => redacted.split(token).join('[REDACTED]'), value.toString());
+}
+
+function createGithubContext(projectRoot, options = {}) {
+  const baseEnv = { ...(options.baseEnv || options.env || process.env) };
+  const account = readGithubAccount(projectRoot, options);
+  if (!account) return createPublicContext(publicStatus('unbound', null, null), null, baseEnv, options);
+  if (!validateGithubLogin(account)) {
+    throw safeCommandFailure('INVALID_GITHUB_LOGIN', 'The clone-local github.account value is not a valid GitHub login.');
+  }
+  return prepareGithubAccount(projectRoot, account, { ...options, baseEnv });
+}
+
+module.exports = {
+  ACCOUNT_KEY,
+  GithubContextError,
+  createGithubContext,
+  prepareGithubAccount,
+  prepareGithubContext: createGithubContext,
+  readGithubAccount,
+  resolveGithubLogin,
+  unsetGithubAccount,
+  validateGithubLogin,
+  writeGithubAccount,
+};

package/lib/global-flags.js

@@ -37,6 +37,7 @@ const GLOBAL_BOOLEAN_FLAGS = new Set([
   '--verbose',
   '--dry-run',
   '--symlink',
+  '--skills-only', '--no-hooks',
   '--sync',
   '--interview',
 ]);

package/lib/hook-renderer.js

@@ -83,6 +83,7 @@ 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';
+const FORGE_READ_ATTENTION_MARKER = 'hooks read-attention';
 // 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).
@@ -134,6 +135,13 @@ const USER_PROMPT_SUBMIT_SUPPORT = Object.freeze({
   hermes: Object.freeze({ rendered: false, reason: 'global-config' }),
 });
 
+const READ_ATTENTION_SUPPORT = Object.freeze({
+  claude: Object.freeze({ rendered: true }),
+  cursor: Object.freeze({ rendered: false, reason: 'no-read-context-surface' }),
+  codex: Object.freeze({ rendered: false, reason: 'global-config' }),
+  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
@@ -161,7 +169,7 @@ function adapterInvocation(harness) {
  * (per-commit) so the rendered Claude PreToolUse groups read write-guard first.
  */
 const FORGE_HOOK_CONTRACT = Object.freeze({
-  schemaVersion: '1.2.0',
+  schemaVersion: '1.3.0',
   kind: 'forge.hookContract',
   adapter: FORGE_HOOK_ADAPTER,
   intents: Object.freeze([
@@ -215,6 +223,14 @@ const FORGE_HOOK_CONTRACT = Object.freeze({
       lifecycle: 'user-prompt-submit',
       command: `${FORGE_CLI} hooks memory-recall`,
     }),
+    Object.freeze({
+      id: 'read-attention',
+      kind: 'context',
+      cliAction: 'read-attention',
+      enforces: 'Read attention: on supported PreToolUse:Read surfaces, inject only memory explicitly scoped to the path being opened. Content is fenced as untrusted, capped, additive, fail-open, and never mutates authority.',
+      lifecycle: 'pre-tool-read',
+      command: `${FORGE_CLI} hooks read-attention`,
+    }),
     Object.freeze({
       id: 'shepherd-events',
       kind: 'context',
@@ -294,6 +310,10 @@ function userPromptSubmitCapability(harness) {
   return USER_PROMPT_SUBMIT_SUPPORT[harness] || { rendered: false, reason: 'unknown-harness' };
 }
 
+function readAttentionCapability(harness) {
+  return READ_ATTENTION_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).
@@ -321,6 +341,10 @@ function renderClaudeHooks(contract) {
         matcher: 'Bash',
         hooks: [{ type: 'command', command: harnessCommand(contract, 'tdd-gate', 'claude') }],
       },
+      {
+        matcher: 'Read',
+        hooks: [{ type: 'command', command: harnessCommand(contract, 'read-attention', 'claude') }],
+      },
     ],
     // SessionStart context injection (memory push). No matcher → applies to every
     // session source; the command emits { hookSpecificOutput.additionalContext }.
@@ -438,6 +462,7 @@ function isForgeCommand(command) {
       || command.includes(FORGE_INBOX_CONTEXT_MARKER)
       || command.includes(FORGE_SHEPHERD_EVENTS_MARKER)
       || command.includes(FORGE_MEMORY_RECALL_MARKER)
+      || command.includes(FORGE_READ_ATTENTION_MARKER)
       || command.includes(FORGE_CAPTURE_CONTEXT_MARKER));
 }
 
@@ -651,13 +676,16 @@ module.exports = {
   FORGE_CONTEXT_MARKER,
   FORGE_INBOX_CONTEXT_MARKER,
   FORGE_MEMORY_RECALL_MARKER,
+  FORGE_READ_ATTENTION_MARKER,
   FORGE_CAPTURE_CONTEXT_MARKER,
   SESSION_START_SUPPORT,
   BOOTSTRAP_DELIVERY,
   USER_PROMPT_SUBMIT_SUPPORT,
+  READ_ATTENTION_SUPPORT,
   SESSION_END_SUPPORT,
   sessionStartCapability,
   userPromptSubmitCapability,
+  readAttentionCapability,
   sessionEndCapability,
   HookConfigParseError,
   renderClaudeHooks,

package/lib/issue-render.js

@@ -114,6 +114,19 @@ function pushSection(lines, label, text) {
   lines.push('', `${label}:`, text);
 }
 
+function renderReadinessReason(reason) {
+	if (!reason || typeof reason !== 'object') return String(reason ?? 'unknown');
+	const detail = reason.field || reason.issue_id || reason.gate || reason.actor || reason.status;
+	const parts = [];
+	if (detail) parts.push(String(detail));
+	if (reason.expected !== undefined) parts.push(`expected ${JSON.stringify(reason.expected)}`);
+	if (reason.actual !== undefined) parts.push(`actual ${JSON.stringify(reason.actual)}`);
+	if (reason.declared !== undefined) parts.push(`declared ${JSON.stringify(reason.declared)}`);
+	return parts.length > 0
+		? `${reason.code} (${parts.join(', ')})`
+		: String(reason.code || 'unknown');
+}
+
 // forge show: the full detail view. This is the surface that prints the FULL id
 // (list/ready show only the 8-char prefix), so every field a script or human
 // needs to act on the issue is reachable without --json.
@@ -135,6 +148,12 @@ function renderIssueShow(envelope) {
   pushField(lines, 'Claimed by', issue.claimed_by);
   pushField(lines, 'Parent', shortId(issue.parent_id ?? null) || null);
   pushField(lines, 'Blocked by', Array.isArray(issue.blocked_by) ? issue.blocked_by.map(shortId) : null);
+	pushField(lines, 'Readiness', issue.readiness_state);
+	pushField(
+		lines,
+		'Readiness reasons',
+		Array.isArray(issue.readiness_reasons) ? issue.readiness_reasons.map(renderReadinessReason) : null,
+	);
   pushField(lines, 'Dependencies', Array.isArray(issue.dependencies) ? issue.dependencies.map(shortId) : null);
   pushField(lines, 'Dependents', Array.isArray(issue.dependents) ? issue.dependents.map(shortId) : null);
   pushField(lines, 'Created', issue.created_at);