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

package/lib/beads-detect.js

@@ -0,0 +1,60 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Single-source, side-effect-free Beads-store detector (kernel issue a5399f3d).
+//
+// Both upgrade-safety surfaces reuse this ONE definition: the issue-path
+// unmigrated-beads nudge (lib/commands/_issue.js) and the `forge upgrade`
+// advisory (lib/upgrade-safety.js). It deliberately lives in a neutral module,
+// NOT in lib/commands/migrate.js — re-exporting a `detectBeadsJsonlSource` name
+// from the migrate command would revive the identifier the a7e1443c
+// implicit-auto-migrate tombstone pins gone (test/commands/runtime-no-auto-migrate).
+// This detector only READS the filesystem and never triggers a migration, so it
+// honors that tombstone's spirit while giving both nudges a shared source.
+
+function dirHasJsonl(dir) {
+  try {
+    return fs.readdirSync(dir).some(entry => entry.endsWith('.jsonl'));
+  } catch (_err) { // NOSONAR S2486 — line-scoped; must sit on the catch line
+    /* intentional: an unreadable directory has no usable jsonl */
+    return false;
+  }
+}
+
+/**
+ * Return the absolute path of the directory holding a returning user's Beads
+ * JSONL under `projectRoot`, or null when none is found. Checks the top-level
+ * `.beads/` first, then the split-store `.beads/backup/` layout (jsonl there and
+ * nowhere else — a layout the migrator itself reads), so neither surface misses
+ * it. Never throws.
+ *
+ * @param {string} [projectRoot]
+ * @returns {string|null}
+ */
+function detectBeadsJsonlSource(projectRoot) {
+  const root = projectRoot || process.cwd();
+  const beadsDir = path.join(root, '.beads');
+  try {
+    if (!fs.existsSync(beadsDir)) {
+      return null;
+    }
+    if (dirHasJsonl(beadsDir)) {
+      return beadsDir;
+    }
+    const backupDir = path.join(beadsDir, 'backup');
+    if (fs.existsSync(backupDir) && dirHasJsonl(backupDir)) {
+      return backupDir;
+    }
+    return null;
+  } catch (_err) { // NOSONAR S2486 — line-scoped; must sit on the catch line
+    /* intentional: an unreadable project root has no detectable beads source */
+    return null;
+  }
+}
+
+module.exports = {
+  detectBeadsJsonlSource,
+  dirHasJsonl,
+};

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

@@ -12,13 +12,14 @@ 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 /
-// --issue-backend kernel / FORGE_ISSUE_BACKEND=kernel; Beads otherwise) and performs
-// any backend-specific argument translation. This module therefore carries NO direct
-// issue-tracker invocation or argv translation — those live in the backend
-// abstraction (lib/forge-issues.js + the issue adapters).
+// runIssueOperation, which dispatches to the Forge Kernel — the only issue backend.
+// This module therefore carries NO direct issue-tracker invocation or argv
+// translation — those live in the backend abstraction (lib/forge-issues.js + the
+// kernel issue adapter).
 const SUBCOMMANDS = {
   create: {
     description: 'Create an issue via Forge',
@@ -64,10 +65,8 @@ const SUBCOMMANDS = {
     description: 'Show issue statistics via Forge',
     usage: 'forge issue stats [flags]',
   },
-  // KAP-7: derived read queries. The backend abstraction maps each to its tracker
-  // equivalent (the Kernel passes the operation name through unchanged; the Beads
-  // backend maps each to its passthrough subcommand). They are READS, so they are
-  // intentionally NOT in WRITE_SUBCOMMANDS.
+  // KAP-7: derived read queries. The Kernel passes the operation name through
+  // unchanged. They are READS, so they are intentionally NOT in WRITE_SUBCOMMANDS.
   blocked: {
     description: 'Show blocked issues via Forge',
     usage: 'forge issue blocked [flags]',
@@ -103,9 +102,7 @@ const SUBCOMMANDS = {
     usage: 'forge issue owns <id> [--json]',
   },
   // Active-lease listing (kernel issue 7dc229d4). A bare passthrough to the Kernel
-  // lease table (kernel_claims); Beads has no lease table to enumerate, so
-  // forge-issues.js rejects the Beads path explicitly. A READ, so intentionally NOT
-  // in WRITE_SUBCOMMANDS.
+  // lease table (kernel_claims). A READ, so intentionally NOT in WRITE_SUBCOMMANDS.
   claims: {
     description: 'Show active issue leases (claims) via Forge',
     usage: 'forge issue claims [--json]',
@@ -386,8 +383,7 @@ function formatIssueHelp() {
 }
 
 // Map a CLI subcommand to the backend operation name. `dep` fans out to
-// `dep.<action>`; every other subcommand uses its own name (the backend performs
-// any tracker-specific translation, e.g. Beads claim -> `update <id> --claim`).
+// `dep.<action>`; every other subcommand uses its own name.
 function resolveIssueOperation(subcommand, args) {
   if (subcommand === 'dep') {
     return `dep.${normalizeArgs(args)[0]}`;
@@ -397,10 +393,8 @@ function resolveIssueOperation(subcommand, args) {
 
 // The Kernel create payload (buildCreatePayload) reads only the --title flag, so a
 // bare leading positional (`forge create "title"`) would be ignored and the title
-// would default to the minted UUID. For parity on the KERNEL PATH ONLY, translate a
-// single leading bare positional into `--title <value>` when no explicit
-// --title/--title= is present. The Beads backend keeps its native positional
-// handling (this never runs for the Beads path).
+// would default to the minted UUID. Translate a single leading bare positional into
+// `--title <value>` when no explicit --title/--title= is present.
 function withKernelCreateTitle(args) {
   const hasTitle = args.some(
     arg => arg === '--title' || (typeof arg === 'string' && arg.startsWith('--title=')),
@@ -451,10 +445,12 @@ function validateDepArgs(args) {
   return null;
 }
 
-// Resolve the active issue backend (kernel|beads) and thread it into opts so the
-// shared runIssueOperation deps see it. OPT-IN ONLY: opts is left byte-identical
-// when no explicit signal is present (env/config/explicit), preserving the Beads
-// default path. A copy is returned — the caller's opts object is never mutated.
+// Normalize any explicit issue-backend signal and thread the resolved value into
+// opts so the shared runIssueOperation deps see it. OPT-IN ONLY: opts is left
+// byte-identical when no explicit signal is present (env/config/explicit), so the
+// no-signal path stays untouched. A copy is returned — the caller's opts object is
+// never mutated. A retired value (`beads`) warns here with the migrate pointer and
+// resolves to the kernel.
 function withResolvedIssueBackend(projectRoot, opts = {}) {
   const env = opts.env || process.env;
   const signalContext = { deps: opts, env, projectRoot };
@@ -476,13 +472,13 @@ function withResolvedIssueBackend(projectRoot, opts = {}) {
 
 // The Kernel broker returns the issue-command contract shape
 // ({ ok, schema_version, command, data, next_commands } or { ok:false, error })
-// rather than the Beads-style { success, output }. The bin/forge.js result printer
+// rather than the legacy { success, output }. The bin/forge.js result printer
 // keys on `success`/`output`, so a raw kernel contract would render as
 // "Command failed". Normalize ONLY the contract shape (ok defined, success
 // undefined) into { success, output } here, at the command boundary — the kernel
 // contract itself stays untouched. Every other result passes through byte-identical.
 //
-// Response-contract parity (the Beads behavior the Kernel replaced):
+// Response-contract guarantees:
 //   * SUCCESS  → the printed envelope carries `ok:true` (consumers gate on it).
 //   * FAILURE  → the contract `exit_code` is surfaced as `result.exitCode` so the bin
 //                printer exits with the error class's code (not always 1); and on
@@ -606,8 +602,7 @@ function splitLeadingIds(args = []) {
 // which broke envelope parity for multi-id close. `ok` is true only when every id
 // closed; per-id outcomes live in `data.results` and the contract `exit_code` of the
 // first failure is surfaced as `exitCode` so the bin printer exits with the error
-// class's code. KERNEL PATH ONLY: the Beads passthrough keeps its single
-// `close id1 id2 ...` invocation.
+// class's code.
 async function runKernelBatchClose(runner, operation, ids, flags, projectRoot, opts, verifyEnabled = false) {
   const results = [];
   let allSucceeded = true;
@@ -697,13 +692,11 @@ async function runIssueSubcommand(subcommand, args, projectRoot, rawOpts = {}) {
     return { success: false, error: `Unknown issue subcommand '${subcommand}'.\n\n${formatIssueHelp()}` };
   }
 
-  // Backend-agnostic --help short-circuit: print the subcommand's usage and return
-  // BEFORE resolving the backend or dispatching any operation. Without this, a help
-  // request was forwarded to the active backend as an operation arg — absorbed
-  // harmlessly by Beads (which swallowed --help), but broken under the Kernel default:
-  // the plural path failed with a bare "Command failed" and the singular path
-  // SILENTLY minted a junk issue (and could queue a GitHub projection). Help must
-  // never touch a backend.
+  // --help short-circuit: print the subcommand's usage and return BEFORE resolving
+  // the backend or dispatching any operation. Without this, a help request is
+  // forwarded to the Kernel as an operation arg: the plural path fails with a bare
+  // "Command failed" and the singular path SILENTLY mints a junk issue (and could
+  // queue a GitHub projection). Help must never touch a backend.
   if (normalizeArgs(args).some(arg => arg === '--help' || arg === '-h')) {
     return { success: true, output: `${spec.usage}\n\n${spec.description}` };
   }
@@ -731,17 +724,31 @@ async function runIssueSubcommand(subcommand, args, projectRoot, rawOpts = {}) {
 
   const opts = withResolvedIssueBackend(projectRoot, rawOpts);
 
-  // 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
-  // honoring an injected runner; the `kernelBroker: opts.kernelBroker` passthrough is
-  // a runtime no-op (undefined under Beads) that documents the Kernel-capable surface.
+  // 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;
+    }
+  }
+
+  // The Kernel is reached through the 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 honoring
+  // an injected runner.
   const runIssueOperation = opts.runIssueOperation || defaultRunIssueOperation;
   const operation = resolveIssueOperation(subcommand, args);
   const operationArgs = resolveOperationArgs(subcommand, args, opts);
 
-  // Check-after-write (gate.issue_verify): resolved ONCE per invocation, kernel
-  // path only. Reads and the Beads path never trigger a read-back.
+  // Check-after-write (gate.issue_verify): resolved ONCE per invocation. Reads never
+  // trigger a read-back.
   const verifyEnabled = VERIFIED_SUBCOMMANDS.has(subcommand)
     && shouldUseKernelBroker(opts)
     && isIssueVerifyEnabled(projectRoot, opts);
@@ -761,7 +768,7 @@ async function runIssueSubcommand(subcommand, args, projectRoot, rawOpts = {}) {
     projectRoot,
     { ...opts, kernelBroker: opts.kernelBroker },
   );
-  // Verify only a SUCCESSFUL kernel-contract mutation (ok:true, not a Beads
+  // Verify only a SUCCESSFUL kernel-contract mutation (ok:true, not a legacy
   // {success,output} shape). Warn-only: attaches verified/mismatches, never
   // changes the result's success or exit code.
   if (verifyEnabled && result && typeof result === 'object' && result.ok === true && result.success === undefined) {
@@ -769,6 +776,23 @@ async function runIssueSubcommand(subcommand, args, projectRoot, rawOpts = {}) {
   }
   // Best-effort, non-blocking: mirror a stage-transition comment into stage_runs.
   recordStageTransitionFromComment(subcommand, operationArgs, result, opts);
+  // 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

@@ -26,7 +26,6 @@ const commands = [
   { file: "add.js", module: require("./add") },
   { file: "audit.js", module: require("./audit") },
   { file: "blocked.js", module: require("./blocked") },
-  { file: "board.js", module: require("./board") },
   { file: "claim.js", module: require("./claim") },
   { file: "claims.js", module: require("./claims") },
   { file: "clean.js", module: require("./clean") },
@@ -48,6 +47,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 +56,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") },
@@ -71,6 +72,7 @@ const commands = [
   { file: "shepherd.js", module: require("./shepherd") },
   { file: "ship.js", module: require("./ship") },
   { file: "show.js", module: require("./show") },
+  { file: "skill.js", module: require("./skill") },
   { file: "stage.js", module: require("./stage") },
   { file: "stale.js", module: require("./stale") },
   { file: "status.js", module: require("./status") },

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