forge-workflow 0.0.10 → 0.1.0-beta.3

package/lib/commands/pr.js

@@ -0,0 +1,88 @@
+'use strict';
+
+const ship = require('./ship');
+const preflight = require('./preflight');
+const shepherd = require('./shepherd');
+const merge = require('./merge');
+const { stripGlobalFlags } = require('../global-flags');
+
+// One memorable surface over the EXISTING pull-request commands (kernel issue
+// 6ab3f30c): every subcommand delegates to the standalone ship/preflight/shepherd/
+// merge handlers — the same code, not a reimplementation. The standalone
+// `forge ship`/`preflight`/`shepherd`/`merge` commands remain registered as
+// back-compat aliases (see lib/commands/_aliases.js), so nothing that already
+// calls them breaks. `pr ship` is the canonical PR-creation form; bare `ship`
+// stays a visible shortcut.
+//
+// Delegates are referenced by MODULE (not a pre-bound `.handler`) so the routed
+// handler is resolved at dispatch time — dispatch always reaches whatever the
+// command module currently exports, keeping the standalone command the single
+// source of truth for its own behaviour.
+const SUBCOMMANDS = {
+  ship: {
+    module: ship,
+    summary: 'Create a pull request from validated feature work (= forge ship)',
+  },
+  preflight: {
+    module: preflight,
+    summary: 'Fast deterministic-gate parity with CI (= forge preflight; supports --all)',
+  },
+  shepherd: {
+    module: shepherd,
+    summary: 'Run one bounded monitor pass over a PR (= forge shepherd; --bundle/--pull/--json, events, watch)',
+  },
+  merge: {
+    module: merge,
+    summary: 'Opt-in conditional auto-merge, OFF by default (= forge merge --auto <pr>)',
+  },
+};
+
+const usage = 'Usage: forge pr <ship|preflight|shepherd|merge> [args]';
+
+function renderHelp() {
+  const width = Math.max(...Object.keys(SUBCOMMANDS).map(name => name.length));
+  const lines = [
+    usage,
+    '',
+    'Subcommands:',
+    ...Object.entries(SUBCOMMANDS).map(
+      ([name, { summary }]) => `  ${name.padEnd(width)}  ${summary}`
+    ),
+    '',
+    'Back-compat: forge ship / forge preflight / forge shepherd / forge merge remain available as aliases.',
+  ];
+  return lines.join('\n');
+}
+
+async function handler(args, flags, projectRoot, opts) {
+  // The subcommand is the first positional token; global flags (e.g. `-p <dir>`) are stripped
+  // first so they never masquerade as the subcommand.
+  const positional = stripGlobalFlags(args).find(arg => !arg.startsWith('-'));
+
+  if (!positional || positional === 'help' || args.includes('--help') || args.includes('-h')) {
+    return { success: true, output: renderHelp() };
+  }
+
+  const sub = SUBCOMMANDS[positional];
+  if (!sub) {
+    return {
+      success: false,
+      error: `Unknown pr subcommand: ${positional}\n\n${renderHelp()}`,
+    };
+  }
+
+  // Forward everything EXCEPT the consumed subcommand token to the delegate, preserving
+  // every remaining token (including flags like `--pull`/`--json`/`--bundle`, and the
+  // `events`/`watch` shepherd sub-shapes) so passthrough stays byte-identical.
+  const idx = args.indexOf(positional);
+  const childArgs = idx >= 0 ? [...args.slice(0, idx), ...args.slice(idx + 1)] : args;
+  return sub.module.handler(childArgs, flags, projectRoot, opts);
+}
+
+module.exports = {
+  name: 'pr',
+  description:
+    'Unified pull-request surface: forge pr ship|preflight|shepherd|merge (wraps ship/preflight/shepherd/merge)',
+  usage,
+  handler,
+};

package/lib/commands/preflight.js

@@ -0,0 +1,211 @@
+'use strict';
+
+/**
+ * `forge preflight` — fast (~2-4 min) blast-radius gate.
+ *
+ * Gives DETERMINISTIC-GATE PARITY with CI so an agent catches what CI catches
+ * WITHOUT waiting on the hanging full suite. Runs four gates in order, fast-fail:
+ *
+ *   1. lint     — eslint --max-warnings 0 on changed files (--all → whole tree)
+ *   2. drift    — skills mirror + registry sync + agentic-workflow structural asserts
+ *   3. sonar    — eslint-plugin-sonarjs cognitive-complexity=15 (+ parity rules)
+ *   4. affected — only the tests mapped from the changed files
+ *
+ * Exit non-zero on any gate failure. Run this before `forge push`.
+ *
+ * @module commands/preflight
+ */
+
+const { execFileSync } = require('node:child_process');
+const { buildGates } = require('../preflight/gates');
+const { runGates } = require('../preflight/runner');
+
+/**
+ * Strictly resolve a base ref to diff HEAD against. Returns the ref name, or
+ * null when no base can be established (fresh repo: no origin/HEAD, no upstream,
+ * no main/master ref). Unlike test.js's resolver, this never falls back to a
+ * default name that doesn't exist — a missing base must be reported, not faked.
+ *
+ * @param {Function} exec - execFileSync-compatible
+ * @returns {string|null}
+ */
+/** Run a git command and return trimmed stdout, or null on any failure. */
+function gitTryOut(exec, args) {
+  try {
+    return String(exec('git', args, { encoding: 'utf8', timeout: 3000, stdio: ['ignore', 'pipe', 'ignore'] }) || '').trim();
+  } catch {
+    return null;
+  }
+}
+
+/** True when `ref` resolves to a real object in this repo. */
+function gitVerifyRef(exec, ref) {
+  try {
+    exec('git', ['rev-parse', '--verify', '--quiet', ref], { stdio: 'ignore', timeout: 3000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * True when `ref` resolves to the SAME commit as HEAD. Diffing HEAD against such
+ * a ref yields zero files, so it is never a usable integration base.
+ */
+function refEqualsHead(exec, ref) {
+  const refSha = gitTryOut(exec, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]);
+  if (!refSha) return false;
+  const headSha = gitTryOut(exec, ['rev-parse', '--verify', '--quiet', 'HEAD^{commit}']);
+  return !!headSha && refSha === headSha;
+}
+
+function resolveBaseRef(exec) {
+  const originHead = gitTryOut(exec, ['rev-parse', '--abbrev-ref', 'origin/HEAD']);
+  if (originHead && originHead !== 'origin/HEAD') return originHead;
+
+  // `@{upstream}` is the CURRENT branch's OWN remote-tracking ref. On a fully
+  // pushed feature branch it points AT HEAD, so diffing against it produces 0
+  // changed files and every gate passes vacuously (fail-OPEN). Accept it as a
+  // base only when it is a real integration point ahead of us — never when it
+  // resolves to our own HEAD. Fall through to a real base (origin/main, …) or
+  // FAIL if none exists, rather than manufacture a wrong-but-'resolved' base.
+  const upstream = gitTryOut(exec, ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}']);
+  if (upstream && !refEqualsHead(exec, upstream)) return upstream;
+
+  for (const ref of ['origin/main', 'origin/master', 'main', 'master']) {
+    if (gitVerifyRef(exec, ref)) return ref;
+  }
+  return null;
+}
+
+/**
+ * Resolve the change set for preflight, distinguishing "base resolved, genuinely
+ * zero changes" from "no base branch could be resolved". Only the latter is a
+ * gate failure — a fresh repo with no base cannot have its blast radius computed,
+ * so preflight must NOT pass vacuously.
+ *
+ * @param {Function} [exec] - execFileSync-compatible (injectable for tests)
+ * @param {{ runAll?: boolean }} [opts]
+ * @returns {{ resolved: boolean, changedFiles: string[], reason?: string, baseRef?: string }}
+ */
+function resolveChangeSet(exec = execFileSync, { runAll = false } = {}) {
+  if (runAll) {
+    return { resolved: true, changedFiles: [], reason: 'whole-tree scope (--all)' };
+  }
+  const baseRef = resolveBaseRef(exec);
+  if (!baseRef) {
+    return {
+      resolved: false,
+      changedFiles: [],
+      reason: 'could not resolve a base branch (no origin/HEAD, no upstream, no main/master ref)',
+    };
+  }
+  // Diff against the SAME base we just resolved. getChangedFiles() re-resolves
+  // its own diff ref (and can fall back to a different default branch), so use
+  // baseRef directly to keep the file list consistent with the resolved base.
+  return { resolved: true, baseRef, changedFiles: changedFilesForBase(exec, baseRef) };
+}
+
+/** Files changed between the merge-base of HEAD and `baseRef` and HEAD. */
+function changedFilesForBase(exec, baseRef) {
+  const mergeBase = gitTryOut(exec, ['merge-base', 'HEAD', baseRef]);
+  const range = mergeBase ? `${mergeBase}...HEAD` : `${baseRef}...HEAD`;
+  const out = gitTryOut(exec, ['diff', '--name-only', range]);
+  if (out == null) return [];
+  return out.split(/\r?\n/).filter(Boolean);
+}
+
+/**
+ * Pick the change set: an injected resolveChangeSet wins; a legacy injected
+ * resolveChangedFiles vouches for resolution; otherwise resolve strictly.
+ */
+function selectChangeSet(deps, runAll) {
+  if (deps.resolveChangeSet) {
+    return deps.resolveChangeSet({ runAll });
+  }
+  if (deps.resolveChangedFiles) {
+    return { resolved: true, changedFiles: deps.resolveChangedFiles() || [] };
+  }
+  return resolveChangeSet(execFileSync, { runAll });
+}
+
+/** Print the fail-closed remedy when no base branch could be resolved. */
+function reportBaseUnresolved(log, reason) {
+  log('forge preflight — fast blast-radius gate (deterministic parity with CI)');
+  log('');
+  log(`preflight FAILED — ${reason}.`);
+  log('  Remedy: give preflight a base branch to diff against, e.g.');
+  log('    git fetch origin && git branch --set-upstream-to=origin/main   # your default branch');
+  log('    (or ensure origin/HEAD is set: git remote set-head origin -a)');
+  log('  Or scan the whole tree explicitly: forge preflight --all');
+}
+
+/** Summary mark for one gate result. */
+function gateMark(result) {
+  if (result.skipped) return 'SKIP';
+  return result.ok ? 'PASS' : 'FAIL';
+}
+
+module.exports = {
+  name: 'preflight',
+  description: 'Fast deterministic-gate parity with CI (lint, drift/registry, sonar, affected tests)',
+  usage: 'forge preflight [--all]',
+  flags: {
+    '--all': 'Lint/scan the whole tree instead of only changed files',
+  },
+
+  /**
+   * @param {string[]} _args
+   * @param {Object} flags
+   * @param {string} projectRoot
+   * @param {Object} [deps] - injectable { log, resolveChangedFiles, buildGates, runGates }
+   * @returns {Promise<{ success: boolean, results?: Array }>}
+   */
+  handler: async (_args, flags, projectRoot, deps = {}) => {
+    const log = deps.log || console.log;
+    const build = deps.buildGates || buildGates;
+    const run = deps.runGates || runGates;
+
+    const runAll = !!(flags && (flags['--all'] || flags.all));
+
+    // Resolve the change set AND whether a base branch could be established.
+    const changeSet = selectChangeSet(deps, runAll) || {};
+
+    // B2 (N1): an unresolvable base is fail-CLOSED. Computing "0 changed files"
+    // from a missing base and passing every gate manufactures false confidence.
+    // Anything not EXPLICITLY resolved (including a missing `resolved` field from
+    // a future override) fails closed — never fail open on an indeterminate base.
+    if (!runAll && !changeSet.resolved) {
+      const reason = changeSet.reason || 'base branch could not be resolved';
+      reportBaseUnresolved(log, reason);
+      return { success: false, results: [], reason, baseUnresolved: true };
+    }
+
+    const changedFiles = changeSet.changedFiles || [];
+
+    log('forge preflight — fast blast-radius gate (deterministic parity with CI)');
+    log(runAll
+      ? '  scope: whole tree (--all)'
+      : `  scope: ${changedFiles.length} changed file(s) vs base branch`);
+    log('');
+
+    const gates = build({ projectRoot, changedFiles, runAll });
+    const { ok, results } = await run(gates, { log: (line) => log(`  ${line}`) });
+
+    log('');
+    log('Preflight summary:');
+    for (const r of results) {
+      const suffix = r.summary ? ` — ${r.summary}` : '';
+      log(`  [${gateMark(r)}] ${r.name}${suffix}`);
+    }
+    log('');
+    log(ok
+      ? 'preflight passed — safe to push'
+      : 'preflight FAILED — fix the failing gate above before `forge push`');
+
+    return { success: ok, results };
+  },
+};
+
+module.exports.resolveChangeSet = resolveChangeSet;
+module.exports.resolveBaseRef = resolveBaseRef;

package/lib/commands/prime.js

@@ -0,0 +1,13 @@
+'use strict';
+
+const {
+  buildPrime,
+  runOrientationCommand,
+} = require('../orientation');
+
+module.exports = {
+  name: 'prime',
+  description: 'Emit session-entry bounded orientation for agents',
+  usage: 'Usage: forge prime [--budget N] [--json]',
+  handler: (args, _flags, projectRoot) => runOrientationCommand(buildPrime, args, projectRoot),
+};

package/lib/commands/push.js

@@ -4,6 +4,8 @@ const { execFileSync, spawnSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
 const forgeToken = require('../../scripts/check-forge-token');
+const { startPrWatcherDetached } = require('../pr-monitor/watch-lifecycle');
+const { autoShepherdRailEnabled } = require('./ship');
 
 const isWindows = process.platform === 'win32';
 
@@ -54,6 +56,113 @@ function isFirstPush(branch, execFn) {
 	}
 }
 
+/**
+ * Resolve the git worktree top-level directory.
+ *
+ * The pre-push hook checks for the nonce token relative to its own cwd, which
+ * git sets to the worktree root during `git push`. The handler's `projectRoot`
+ * is derived from INIT_CWD/cwd and can point at the MAIN repo root when forge
+ * runs from a linked worktree, so the token must be written to the real git
+ * top-level instead — otherwise lefthook never finds it and re-runs the suite.
+ *
+ * @param {function} execFn - execFileSync or mock
+ * @param {string} fallback - projectRoot to use when git resolution fails
+ * @returns {string} Absolute worktree top-level path, or the fallback
+ */
+function resolveGitToplevel(execFn, fallback) {
+	try {
+		const top = execFn('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim();
+		return top || fallback;
+	} catch (_err) { /* intentional: fall back to projectRoot outside a git worktree */ // NOSONAR S2486
+		return fallback;
+	}
+}
+
+/**
+ * Auto-file rail: best-effort, NON-BLOCKING ensure that the branch being pushed has a
+ * backing Kernel issue (kernel issue a4b8f56f) — so started work that is being pushed
+ * never goes unfiled. Idempotent (deduped by branch via ensureBackingIssue); a
+ * main/master/detached/ignore branch is skipped, and ANY failure degrades to null and
+ * NEVER aborts the push. Injectable via `deps._ensureBackingIssue` for tests.
+ *
+ * @param {string} projectRoot
+ * @param {function} execFn - execFileSync (for branch resolution)
+ * @param {object} deps - DI (may inject `_ensureBackingIssue`, `_kernelDriver`, `_kernelBroker`)
+ * @returns {Promise<object|null>}
+ */
+async function autoFileBackingIssueForPush(projectRoot, execFn, deps = {}) {
+  try {
+    // Lazy require INSIDE the try: a module-load failure must degrade to null and
+    // NEVER abort the push (mirrors the worktree helper; CodeRabbit #370).
+    const ensure = deps._ensureBackingIssue || require('../kernel/backing-issue').ensureBackingIssue;
+    const branch = getCurrentBranch(execFn);
+    if (!branch || branch === 'unknown') return null;
+    let driver = deps._kernelDriver;
+    let broker = deps._kernelBroker;
+    if (!driver || !broker) {
+      if (!fs.existsSync(path.join(projectRoot, '.git'))) return null;
+      const { buildMigratedKernelIssueDeps } = require('../kernel/cli-broker-factory');
+      const built = await buildMigratedKernelIssueDeps({ projectRoot });
+      driver = driver || built.kernelDriver;
+      broker = broker || built.kernelBroker;
+    }
+    return await ensure({ branch, projectRoot, driver, broker });
+  } catch (_err) { /* non-blocking: tracking must never break a push */ // NOSONAR S2486
+    return null;
+  }
+}
+
+/**
+ * Resolve the OPEN PR number for the current branch via `gh pr view`. Returns
+ * null when there is no PR, gh is unavailable, or anything errors (fail-open).
+ * NEVER throws.
+ *
+ * @param {function} execFn - execFileSync or mock
+ * @returns {number|null}
+ */
+function resolveOpenPrNumber(execFn) {
+	try {
+		const out = execFn('gh', ['pr', 'view', '--json', 'number', '-q', '.number'], {
+			encoding: 'utf8', timeout: 15000, stdio: ['pipe', 'pipe', 'pipe'],
+		});
+		const n = Number.parseInt(String(out).trim(), 10);
+		return Number.isInteger(n) && n > 0 ? n : null;
+	} catch (_err) { /* intentional: no open PR / gh missing → arm nothing */ // NOSONAR S2486
+		return null;
+	}
+}
+
+/**
+ * Best-effort, NON-BLOCKING arm of the constant PR watcher after a successful
+ * push, when an OPEN PR exists for the current branch. This closes the gap where
+ * PRs not born from `forge ship` (gh pr create, the GitHub UI, an earlier push)
+ * never got a watcher. Gated by the default-ON `rail.auto_shepherd`, idempotent
+ * via the watch loop's own PID/journal lock, and reusing the same
+ * `startPrWatcherDetached` as ship. MUST NEVER throw into or fail the push: a
+ * disabled rail, no PR, a gh error, or a spawn error all degrade to
+ * `{ armed: false }`.
+ *
+ * @param {object} params
+ * @returns {{ armed: boolean, reason?: string, prNumber?: number }}
+ */
+function maybeArmWatcherAfterPush({
+	projectRoot,
+	execFn,
+	startWatcher = startPrWatcherDetached,
+	railEnabled = autoShepherdRailEnabled,
+	prLookup = resolveOpenPrNumber,
+}) {
+	try {
+		if (!railEnabled(projectRoot)) return { armed: false, reason: 'rail.auto_shepherd disabled' };
+		const prNumber = prLookup(execFn);
+		if (!prNumber) return { armed: false, reason: 'no-open-pr' };
+		const res = startWatcher({ prNumber, cwd: projectRoot });
+		return { armed: !!(res && res.started), reason: res && res.reason, prNumber };
+	} catch (err) {
+		return { armed: false, reason: err.message };
+	}
+}
+
 /**
  * Run branch protection check as a subprocess.
  * @param {function} execFn - execFileSync or mock
@@ -150,6 +259,10 @@ module.exports = {
 			return { success: false, quickMode, lintPassed: false, pushed: false };
 		}
 
+		// Auto-file rail (non-blocking): ensure the branch being pushed has a backing
+		// Kernel issue so started work never goes unfiled. Never aborts the push.
+		await autoFileBackingIssueForPush(projectRoot, execFn, deps || {});
+
 		// Step 2: Lint
 		const lintPassed = runLint(spawnFn, pkgManager, projectRoot);
 		if (!lintPassed) {
@@ -163,9 +276,11 @@ module.exports = {
 			return { success: false, quickMode, lintPassed: true, testsPassed: false, pushed: false };
 		}
 
-		// Step 4: Write nonce token so lefthook skips pre-push hooks
+		// Step 4: Write nonce token so lefthook skips pre-push hooks.
+		// Write to the git worktree top-level (where the hook checks), not the
+		// inherited projectRoot, so the skip works from linked worktrees too.
 		try {
-			tokenWrite(projectRoot);
+			tokenWrite(resolveGitToplevel(execFn, projectRoot));
 		} catch (_err) { /* intentional: non-fatal, lefthook will re-run hooks */ // NOSONAR S2486
 			log('Warning: Could not write forge push token — lefthook hooks will run again');
 		}
@@ -185,6 +300,17 @@ module.exports = {
 			};
 		}
 
+		// Arm the constant PR watcher for this branch's open PR (best-effort,
+		// gated by rail.auto_shepherd, never fails the push). Covers PRs not born
+		// from `forge ship`.
+		maybeArmWatcherAfterPush({
+			projectRoot,
+			execFn,
+			startWatcher: deps?.startWatcher,
+			railEnabled: deps?.railEnabled,
+			prLookup: deps?.prLookup,
+		});
+
 		return {
 			success: true,
 			quickMode,
@@ -193,4 +319,11 @@ module.exports = {
 			pushed: true,
 		};
 	},
+
+	// Exposed for unit tests; not part of the CLI surface.
+	_internal: {
+		autoFileBackingIssueForPush,
+		maybeArmWatcherAfterPush,
+		resolveOpenPrNumber,
+	},
 };

package/lib/commands/ready.js

@@ -1,5 +1,5 @@
 'use strict';
 
-const { makeAliasCommand } = require('./_issue');
+const { createIssueSubcommand } = require('./_issue');
 
-module.exports = makeAliasCommand('ready');
+module.exports = createIssueSubcommand('ready');

package/lib/commands/recall.js

@@ -0,0 +1,171 @@
+'use strict';
+
+const memoryRouter = require('../memory/router');
+const { stripGlobalFlags } = require('../global-flags');
+const { fenceUntrusted } = require('../untrusted-content');
+
+const usage = 'Usage: forge recall [query] [--kind <type>] [--limit N] [--all] [--json]';
+
+// Reserved tag prefix that `remember --kind` writes (kernel issue 8cc1db4d). A `--kind`
+// filter keeps only notes carrying this tag; the prefix is stripped when surfacing the
+// derived `type` field so a note's user tags stay clean. The filter FLAG is `--kind` (NOT
+// `--type`): `--type` is a reserved GLOBAL flag hard-validated to workflow classifications.
+const TYPE_TAG_PREFIX = 'type:';
+
+// When a `--kind` filter is active the tag filter runs in the command layer (the store is
+// not reimplemented), so scan a generous window of recent notes before filtering rather than
+// the small default page — otherwise the type match could fall outside the default limit.
+const TYPE_FILTER_SCAN = 1000;
+
+/**
+ * Separate the optional positional query from `--kind <type>`, `--limit N`, and `--json`.
+ * Global flags (e.g. `-p <dir>`, `--all`) are stripped first so they never corrupt the
+ * search query (kernel issue c1e090ff). `--all` is a GLOBAL boolean flag, so the handler
+ * reads it from its `flags` argument (or the raw args on a direct call) — not from here.
+ * `--kind` is NOT a global flag, so it survives the strip and is parsed here.
+ *
+ * @param {string[]} rawArgs - Raw command arguments.
+ * @returns {{ query: string, limit: (number|undefined), type: (string|undefined), json: boolean }}
+ */
+function parseArgs(rawArgs) {
+  const args = stripGlobalFlags(rawArgs);
+  const words = [];
+  let limit;
+  let type;
+  let json = false;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--json') {
+      json = true;
+    } else if (arg === '--limit') {
+      const value = Number(args[index + 1]);
+      if (Number.isInteger(value) && value > 0) {
+        limit = value;
+        index += 1;
+      }
+    } else if (arg.startsWith('--limit=')) {
+      const value = Number(arg.slice('--limit='.length));
+      if (Number.isInteger(value) && value > 0) {
+        limit = value;
+      }
+    } else if (arg === '--kind') {
+      const value = args[index + 1];
+      if (value && !value.startsWith('--')) {
+        type = value.trim();
+        index += 1;
+      }
+    } else if (arg.startsWith('--kind=')) {
+      type = arg.slice('--kind='.length).trim();
+    } else {
+      words.push(arg);
+    }
+  }
+
+  return { query: words.join(' ').trim(), limit, type, json };
+}
+
+// Derive a note's `type` from its reserved `type:` tag (undefined when untyped), so any
+// surface — JSON and text — can show and filter by kind without exposing the tag encoding.
+function typeOf(entry) {
+  const tag = (entry.tags || []).find(t => t.startsWith(TYPE_TAG_PREFIX));
+  return tag ? tag.slice(TYPE_TAG_PREFIX.length) : undefined;
+}
+
+function withType(entry) {
+  const type = typeOf(entry);
+  return type ? { ...entry, type } : entry;
+}
+
+function formatEntry(entry) {
+  const date = entry.timestamp ? entry.timestamp.slice(0, 10) : '';
+  const prefix = date ? `${date}  ` : '';
+  // The reserved `type:` tag renders as a leading `(kind)` marker, not as a raw tag, so the
+  // displayed tags stay the user's own labels.
+  const type = typeOf(entry);
+  const userTags = (entry.tags || []).filter(t => !t.startsWith(TYPE_TAG_PREFIX));
+  const tagSuffix = userTags.length > 0 ? ` [${userTags.join(', ')}]` : '';
+  const typeMarker = type ? `(${type}) ` : '';
+  // Machine/insights records are LABELED with their source so they are never mistaken for a
+  // plain human note; human `remember` notes render clean.
+  const marker = entry.machine && entry.sourceAgent ? `(${entry.sourceAgent}) ` : '';
+  // Stored note text is UNTRUSTED (a planted memory could carry injected directives),
+  // so the human/agent-facing render is provenance-fenced. The `--json` path above
+  // keeps the raw note so programmatic consumers/parsers are unaffected.
+  const note = fenceUntrusted(entry.note, { source: 'memory' });
+  return `- ${prefix}${marker}${typeMarker}${note}${tagSuffix}`;
+}
+
+async function handler(args, flags, projectRoot) {
+  const { query, limit, type, json } = parseArgs(args);
+  // `--all` is a GLOBAL boolean flag: in production bin/forge.js strips it from
+  // args and sets flags.all; on a direct handler call it may still be in args.
+  const all = Boolean(flags && flags.all) || args.includes('--all');
+
+  // A `--type` filter scans a generous recent window, then keeps only matching notes — the
+  // read stays entirely in the existing store (no schema change). `--limit` is re-applied
+  // AFTER filtering so it caps the typed result set, not the pre-filter scan.
+  const recallLimit = type ? Math.max(limit ?? 0, TYPE_FILTER_SCAN) : limit;
+  const result = memoryRouter.recall(projectRoot, { query, limit: recallLimit, all });
+  let notes = result.notes.map(withType);
+  let { total, capped } = result;
+  const { scope } = result;
+  if (type) {
+    notes = notes.filter(entry => entry.type === type);
+    total = notes.length;
+    if (limit && notes.length > limit) {
+      notes = notes.slice(0, limit);
+      capped = true;
+    } else {
+      capped = false;
+    }
+  }
+
+  if (json) {
+    // Object (not a bare array) so programmatic consumers see the total and whether the
+    // result was truncated (raise --limit to page further).
+    return {
+      success: true,
+      output: `${JSON.stringify({ notes, total, capped, scope }, null, 2)}\n`,
+    };
+  }
+
+  if (notes.length === 0) {
+    const reason = query
+      ? `No notes match "${query}".`
+      : 'No notes remembered yet. Use "forge remember <note>" to add one.';
+    return { success: true, output: reason };
+  }
+
+  const noun = scope === 'all' && !query ? 'stored memory record(s)' : 'remembered note(s)';
+  let header;
+  if (query) {
+    // BM25 returns at most `limit`; when full, signal it is the TOP-N, not the whole set.
+    header = capped
+      ? `Top ${notes.length} note(s) matching "${query}" (raise --limit for more):`
+      : `${notes.length} note(s) matching "${query}":`;
+  } else if (capped) {
+    // Never a bare full dump: show the newest N and the true total.
+    header = `Showing ${notes.length} of ${total} ${noun} (newest first):`;
+  } else {
+    header = `${total} ${noun}:`;
+  }
+  const lines = notes.map(formatEntry);
+  return {
+    success: true,
+    output: [header, ...lines].join('\n'),
+  };
+}
+
+module.exports = {
+  name: 'recall',
+  description: 'Retrieve project-memory notes from the kernel-backed memory store',
+  usage,
+  flags: {
+    '--kind': 'Filter to notes of a type (decision|bugfix|gotcha|...); --type is reserved',
+    '--limit': 'Cap the number of notes returned',
+    '--all': 'Include machine/insights records in the no-query listing (query already searches all)',
+    '--json': 'Emit machine-readable JSON output',
+  },
+  handler,
+};