forge-workflow 0.0.10 → 0.1.0-beta.2

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

@@ -54,6 +54,62 @@ 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;
+  }
+}
+
 /**
  * Run branch protection check as a subprocess.
  * @param {function} execFn - execFileSync or mock
@@ -150,6 +206,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 +223,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');
 		}
@@ -193,4 +255,9 @@ module.exports = {
 			pushed: true,
 		};
 	},
+
+	// Exposed for unit tests; not part of the CLI surface.
+	_internal: {
+		autoFileBackingIssueForPush,
+	},
 };

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,116 @@
+'use strict';
+
+const memoryRouter = require('../memory/router');
+const { stripGlobalFlags } = require('../global-flags');
+const { fenceUntrusted } = require('../untrusted-content');
+
+const usage = 'Usage: forge recall [query] [--limit N] [--all] [--json]';
+
+/**
+ * Separate the optional positional query from `--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 this parsed query.
+ *
+ * @param {string[]} rawArgs - Raw command arguments.
+ * @returns {{ query: string, limit: (number|undefined), json: boolean }}
+ */
+function parseArgs(rawArgs) {
+  const args = stripGlobalFlags(rawArgs);
+  const words = [];
+  let limit;
+  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 {
+      words.push(arg);
+    }
+  }
+
+  return { query: words.join(' ').trim(), limit, json };
+}
+
+function formatEntry(entry) {
+  const date = entry.timestamp ? entry.timestamp.slice(0, 10) : '';
+  const prefix = date ? `${date}  ` : '';
+  const tagSuffix = entry.tags.length > 0 ? ` [${entry.tags.join(', ')}]` : '';
+  // 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}${note}${tagSuffix}`;
+}
+
+async function handler(args, flags, projectRoot) {
+  const { query, limit, 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');
+
+  const { notes, total, capped, scope } = memoryRouter.recall(projectRoot, { query, limit, all });
+
+  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: {
+    '--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,
+};

package/lib/commands/recap.js

@@ -0,0 +1,61 @@
+'use strict';
+
+const {
+  buildIssueRecap,
+  formatOrientationText,
+} = require('../orientation');
+
+const usage = 'Usage: forge recap <issue> [--budget N] [--json]';
+
+// Options that consume the following token as their value. The issue-id scan
+// must skip these values so `forge recap --budget 220 <issue>` is not misread.
+const OPTIONS_WITH_VALUES = new Set(['--budget']);
+
+function readOption(args, name, fallback) {
+  const equals = args.find(arg => arg.startsWith(`${name}=`));
+  if (equals) return equals.slice(name.length + 1);
+  const index = args.indexOf(name);
+  if (index >= 0 && args[index + 1] && !args[index + 1].startsWith('-')) return args[index + 1];
+  return fallback;
+}
+
+function readIssueArg(args) {
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg) continue;
+    if (OPTIONS_WITH_VALUES.has(arg)) {
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith('-')) continue;
+    return arg;
+  }
+  return null;
+}
+
+// `forge recap <issue>` summarizes a single issue from the deterministic
+// orientation source assembly — it is issue-scoped, not a project-wide recap.
+async function handler(args, _flags, projectRoot) {
+  const issueId = readIssueArg(args);
+  if (!issueId) {
+    // Use `error` (not `output`) so the CLI dispatcher prints the usage line
+    // once via console.error instead of also appending a redundant bare
+    // "Command failed" (see bin/forge.js registry dispatch).
+    return { success: false, error: usage };
+  }
+
+  const recap = buildIssueRecap(projectRoot, issueId, {
+    budgetTokens: readOption(args, '--budget', undefined),
+  });
+  return {
+    success: true,
+    output: args.includes('--json') ? `${JSON.stringify(recap, null, 2)}\n` : formatOrientationText(recap),
+  };
+}
+
+module.exports = {
+  name: 'recap',
+  description: 'Summarize a single issue from deterministic orientation source files',
+  usage,
+  handler,
+};

package/lib/commands/recommend.js

@@ -23,7 +23,6 @@ const STAGE_NAMES = {
   validate: 'Validate',
   ship: 'Ship',
   review: 'Review',
-  premerge: 'Premerge',
 };
 
 /**

package/lib/commands/release.js

@@ -0,0 +1,91 @@
+'use strict';
+
+const {
+  SUPPORTED_TARGET,
+  buildReadinessReport,
+  renderReadinessReport,
+} = require('../release-readiness');
+const { runIssueOperation: defaultRunIssueOperation } = require('../forge-issues');
+const { normalizeArgs, normalizeIssueResult, withResolvedIssueBackend } = require('./_issue');
+
+// `forge release <id>` releases a claimed issue; `forge release check` runs the
+// release-readiness gate. The two share the top-level verb, so this command
+// dispatches `check` to the gate and routes everything else through the shared
+// issue dispatch (resolve backend → runIssueOperation('release') → normalize). The
+// Beads backend has no release op and returns the Kernel-only contract error.
+const usage = 'Usage: forge release <id>  |  forge release check --target 0.1.0 [--json]';
+
+async function runReleaseIssue(args, projectRoot, opts = {}) {
+  const resolved = withResolvedIssueBackend(projectRoot, opts);
+  const runIssueOperation = resolved.runIssueOperation || defaultRunIssueOperation;
+  const normalizedArgs = normalizeArgs(args);
+  const result = await runIssueOperation('release', normalizedArgs, projectRoot,
+    { ...resolved, kernelBroker: resolved.kernelBroker });
+  return normalizeIssueResult(result, 'release', { json: normalizedArgs.includes('--json') });
+}
+
+function readOption(args, name, fallback) {
+  const equals = args.find(arg => arg.startsWith(`${name}=`));
+  if (equals) {
+    return equals.slice(name.length + 1);
+  }
+
+  const index = args.indexOf(name);
+  if (index >= 0 && args[index + 1] && !args[index + 1].startsWith('-')) {
+    return args[index + 1];
+  }
+
+  return fallback;
+}
+
+function parseReleaseArgs(args = []) {
+  const subcommand = args.find((arg, index) => {
+    if (arg.startsWith('-')) {
+      return false;
+    }
+    const previous = args[index - 1];
+    return previous !== '--target';
+  });
+
+  return {
+    subcommand,
+    target: readOption(args, '--target', SUPPORTED_TARGET),
+    json: args.includes('--json'),
+  };
+}
+
+async function handler(args, _flags, projectRoot, opts = {}) {
+  const parsed = parseReleaseArgs(args);
+
+  if (parsed.subcommand !== 'check') {
+    // forge release <id> — release a claimed issue via the shared issue dispatch.
+    return runReleaseIssue(args, projectRoot, opts);
+  }
+
+  const report = buildReadinessReport(projectRoot, { target: parsed.target });
+  const output = parsed.json
+    ? `${JSON.stringify(report, null, 2)}\n`
+    : renderReadinessReport(report);
+  const error = parsed.json
+    ? `Forge release readiness check failed for ${report.target}`
+    : output;
+
+  return {
+    success: report.success,
+    report,
+    output,
+    error: report.success ? undefined : error,
+  };
+}
+
+module.exports = {
+  name: 'release',
+  description: 'Release a claimed issue, or run Forge release readiness gates (forge release check)',
+  usage,
+  flags: {
+    '--target <version>': 'Release target to check',
+    '--json': 'Emit the readiness report as JSON',
+  },
+  handler,
+  parseReleaseArgs,
+};

package/lib/commands/remember.js

@@ -0,0 +1,74 @@
+'use strict';
+
+const memoryRouter = require('../memory/router');
+const { stripGlobalFlags } = require('../global-flags');
+
+const usage = 'Usage: forge remember <note> [--tag <label>]... [--json]';
+
+/**
+ * Split positional note words from `--tag <label>` pairs and the `--json` flag.
+ * Global flags (e.g. `-p <dir>`) are stripped first so they never leak into
+ * the stored note content (kernel issue c1e090ff).
+ *
+ * @param {string[]} rawArgs - Raw command arguments.
+ * @returns {{ note: string, tags: string[], json: boolean }}
+ */
+function parseArgs(rawArgs) {
+  const args = stripGlobalFlags(rawArgs);
+  const words = [];
+  const tags = [];
+  let json = false;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--json') {
+      json = true;
+    } else if (arg === '--tag') {
+      const value = args[index + 1];
+      if (value && !value.startsWith('--')) {
+        tags.push(value);
+        index += 1;
+      }
+    } else if (arg.startsWith('--tag=')) {
+      tags.push(arg.slice('--tag='.length));
+    } else {
+      words.push(arg);
+    }
+  }
+
+  return { note: words.join(' ').trim(), tags, json };
+}
+
+async function handler(args, _flags, projectRoot) {
+  const { note, tags, json } = parseArgs(args);
+
+  if (!note) {
+    return {
+      success: false,
+      error: `No note provided.\n${usage}`,
+    };
+  }
+
+  const entry = memoryRouter.append(projectRoot, note, { tags });
+
+  if (json) {
+    return { success: true, output: `${JSON.stringify(entry, null, 2)}\n` };
+  }
+
+  const tagSuffix = entry.tags.length > 0 ? ` [${entry.tags.join(', ')}]` : '';
+  return {
+    success: true,
+    output: `Remembered: ${entry.note}${tagSuffix}`,
+  };
+}
+
+module.exports = {
+  name: 'remember',
+  description: 'Persist a project-memory note to the kernel-backed memory store',
+  usage,
+  flags: {
+    '--tag': 'Attach a search label (repeatable)',
+    '--json': 'Emit machine-readable JSON output',
+  },
+  handler,
+};