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

package/lib/commands/init.js

@@ -335,27 +335,40 @@ function renderDayOneConfigYaml({ profile, classification, harnessTargets, rails
   config.workflow.classification = { default: classification };
   config.layer1Rails = {
     confirmed: railsConfirmed,
+    // The immutable Layer 1 floor: locked rails that cannot be toggled off.
     rails: [
-      'tdd_intent',
       'secret_scan',
       'branch_protection',
       'signed_commits',
       'schema_integrity',
     ],
+    // tdd_intent is a strong DEFAULT rail, not an immutable L1 floor: it is unlocked
+    // (locked:false) and honestly toggleable via `forge gate disable rail.tdd_intent`
+    // (the minimal profile ships it off). Listed separately so this display never
+    // implies it is a non-negotiable Layer 1 rail (issue eda6d866).
+    toggleableRails: ['tdd_intent'],
   };
   config.adapters = config.adapters || {};
   config.adapters.harness = {
     enabled: harnessTargets.length > 0,
     targets: harnessTargets,
   };
-  config.protectedPaths = [
-    ...new Set([
-      ...(Array.isArray(config.protectedPaths) ? config.protectedPaths : []),
-      '.forge/config.yaml',
-      '.forge/patch.md',
-      '.forge/protected-paths.yaml',
-    ]),
-  ];
+  // The adoption profile is authoritative for whether protected-path enforcement runs
+  // at all. When it resolves EMPTY (the `minimal` profile = zero active enforcement),
+  // the protected-path guard must stay genuinely inert — do NOT re-add the day-one
+  // paths, or `init --minimal` would silently reactivate the guard the profile just
+  // disabled (issue eda6d866). Standard/full keep their profile paths + the additions.
+  const profilePaths = Array.isArray(config.protectedPaths) ? config.protectedPaths : [];
+  config.protectedPaths = profilePaths.length === 0
+    ? []
+    : [
+        ...new Set([
+          ...profilePaths,
+          '.forge/config.yaml',
+          '.forge/patch.md',
+          '.forge/protected-paths.yaml',
+        ]),
+      ];
   return YAML.stringify(config);
 }
 
@@ -543,24 +556,17 @@ async function handler(args, flags, projectRoot = process.cwd(), deps = {}) {
   }
 
   // Close the onboarding loop that a bare `forge init` used to leave open:
-  //  1. install git hooks so stage commands are not HOOKS_NOT_ACTIVE-blocked, and
-  //  2. import any existing Beads store into the Kernel.
-  // Both reuse setup's real implementations (overridable via deps for tests) and
-  // degrade to a warning rather than failing init.
+  // install git hooks so stage commands are not HOOKS_NOT_ACTIVE-blocked. Reuses
+  // setup's real implementation (overridable via deps for tests) and degrades to a
+  // warning rather than failing init. Beads → Kernel transfer is NOT done here: it
+  // is explicit-only via `forge migrate --from beads` (a7e1443c), never implicit.
   const installHooks = deps.installHooks
     || ((root) => require('./setup').ensureGitHooksInstalled(root));
-  const autoMigrateBeads = deps.autoMigrateBeads
-    || ((root) => require('./migrate').autoMigrateBeadsIfPresent(root));
   try {
     await installHooks(projectRoot);
   } catch (err) {
     console.warn(`Warning: git hook installation skipped: ${err.message}`);
   }
-  try {
-    await autoMigrateBeads(projectRoot);
-  } catch (err) {
-    console.warn(`Warning: Beads → Kernel migration skipped: ${err.message}`);
-  }
 
   console.log(`Initialized Forge adoption profile '${profile}' at .forge/`);
   console.log(`Classification: ${choices.classification}`);

package/lib/commands/memory.js

@@ -0,0 +1,81 @@
+'use strict';
+
+const remember = require('./remember');
+const recall = require('./recall');
+const insights = require('./insights');
+const { stripGlobalFlags } = require('../global-flags');
+
+// One memorable surface over the EXISTING memory commands (kernel issue 25362344): every
+// subcommand delegates to the standalone remember/recall/insights handlers — the same
+// kernel-backed store, not a reimplementation. The standalone `forge remember`/`forge
+// recall`/`forge insights` commands remain registered as back-compat aliases, so nothing
+// that already calls them breaks.
+const SUBCOMMANDS = {
+  add: {
+    handler: remember.handler,
+    summary: 'Persist a memory note (= forge remember; supports --type + What/Why/Where/Learned)',
+  },
+  recall: {
+    handler: recall.handler,
+    summary: 'Retrieve memory notes, newest first (= forge recall; filter with --type)',
+  },
+  search: {
+    // Search IS recall with a query — recall runs a BM25 token-AND search when a query is
+    // present, so the same handler serves both without a second code path.
+    handler: recall.handler,
+    summary: 'Search memory notes by query (recall with a query; filter with --type)',
+  },
+  insights: {
+    handler: insights.handler,
+    summary: 'Detect recurring evidence patterns and suggest follow-ups (= forge insights)',
+  },
+};
+
+const usage = 'Usage: forge memory <add|recall|search|insights> [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 remember / forge recall / forge insights 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 memory subcommand: ${positional}\n\n${renderHelp()}`,
+    };
+  }
+
+  // Forward everything EXCEPT the consumed subcommand token to the delegate, preserving any
+  // global flags the delegate re-parses (e.g. `-p <dir>`, `--all`).
+  const idx = args.indexOf(positional);
+  const childArgs = idx >= 0 ? [...args.slice(0, idx), ...args.slice(idx + 1)] : args;
+  return sub.handler(childArgs, flags, projectRoot, opts);
+}
+
+module.exports = {
+  name: 'memory',
+  description:
+    'Unified memory surface: forge memory add|recall|search|insights (wraps remember/recall/insights)',
+  usage,
+  handler,
+};

package/lib/commands/migrate.js

@@ -301,171 +301,10 @@ async function runBeadsMigration(options, projectRoot, opts) {
   }
 }
 
-/**
- * Detect a jsonl-backed Beads store under `<projectRoot>/.beads`. Returns the
- * directory path when it holds *.jsonl sidecars, else null.
- *
- * Onboarding (forge setup/init) uses this to decide whether to auto-migrate.
- * It deliberately never falls back to `bd export` (a Dolt-only store with no
- * jsonl returns null), so setup stays bd-free even when Dolt is down.
- */
-function detectBeadsJsonlSource(projectRoot, deps = {}) {
-  const fsImpl = deps.fs || fs;
-  const beadsDir = path.join(projectRoot || process.cwd(), '.beads');
-  return fsImpl.existsSync(beadsDir) && directoryHasJsonl(beadsDir, fsImpl)
-    ? beadsDir
-    : null;
-}
-
-/**
- * Idempotently import an existing jsonl-backed Beads store into the Kernel as
- * part of onboarding. Reuses the exact `forge migrate --from beads` spine, so
- * gaps are surfaced honestly and a second run inserts nothing.
- *
- * No-op (`{ migrated: false, reason: 'no-beads-jsonl' }`) when there is no jsonl
- * `.beads/` present. Never requires the `bd` binary.
- *
- * @param {string} projectRoot
- * @param {object} [opts] - Passed through to runBeadsMigration (_broker/_now/_fs seams).
- * @returns {Promise<{ migrated: boolean, reason?: string, result?: object }>}
- */
-async function autoMigrateBeadsIfPresent(projectRoot, opts = {}) {
-  if (!detectBeadsJsonlSource(projectRoot, { fs: opts._fs })) {
-    return { migrated: false, reason: 'no-beads-jsonl' };
-  }
-  const result = await runBeadsMigration({ from: 'beads' }, projectRoot, opts);
-  return { migrated: result.success === true, result };
-}
-
-const BEADS_MIGRATE_NUDGE =
-  'Forge could not import your Beads issues into the Kernel automatically. '
-  + 'Run `forge migrate --from beads` to import them.';
-
-// The "already imported" marker lives as a row in the broker's kernel_migrations
-// ledger (created unconditionally by broker.initialize()), NOT as a file beside the
-// DB. Keeping it INSIDE the kernel DB means a DB reset drops the marker and the import
-// self-heals; a file sentinel would survive the reset and leave issues dark forever.
-// The id uses underscores so it passes the ledger charset /^[0-9a-z_]+$/i and stays
-// clear of the tokens the D20 retirement audit counts (see release-readiness.js).
-const IMPORT_MARKER_TABLE = 'kernel_migrations';
-const IMPORT_MARKER_ID = 'data_import_beads_jsonl';
-
-// Read/record the import marker via the DRIVER (the broker exposes no raw SQL). Both
-// calls are param-less (raw SQL + config); the id is a hardcoded constant and appliedAt
-// is an ISO string, so interpolation is injection-safe — mirrors broker.recordMigrationSql.
-async function importMarkerPresent(driver, config) {
-  if (!driver || typeof driver.queryAll !== 'function') {
-    return false;
-  }
-  try {
-    const rows = await driver.queryAll(
-      `SELECT 1 FROM ${IMPORT_MARKER_TABLE} WHERE id = '${IMPORT_MARKER_ID}' LIMIT 1;`,
-      config,
-    );
-    return Array.isArray(rows) && rows.length > 0;
-  } catch {
-    // Ledger table absent / driver unavailable → treat as not-yet-imported.
-    return false;
-  }
-}
-
-async function recordImportMarker(driver, config, appliedAt) {
-  if (!driver || typeof driver.exec !== 'function') {
-    return;
-  }
-  try {
-    await driver.exec(
-      `INSERT OR IGNORE INTO ${IMPORT_MARKER_TABLE} (id, applied_at) VALUES ('${IMPORT_MARKER_ID}', '${appliedAt}');`,
-      config,
-    );
-  } catch {
-    // Best-effort marker; never break the command we ride on.
-  }
-}
-
-/**
- * First-use safety net for the kernel default backend. Onboarding auto-migrate runs
- * only from `forge setup`/`init`; an existing repo whose user merely upgrades forge
- * reads an EMPTY kernel on the first issue command, so their existing Beads issues
- * appear to vanish. This imports them ONCE — gated by an in-DB marker row in the
- * kernel_migrations ledger, so the gate shares the DB lifecycle and a DB reset
- * self-heals — idempotently, announcing on stderr only so `--json` stdout stays a pure
- * contract. NEVER throws: the safety net must never break the command it rides on.
- *
- * Only a jsonl-backed store is auto-imported (the migration binary is never shelled).
- * A store with no jsonl export is skipped silently. The marker is SUCCESS-ONLY: a
- * failed import records nothing and is retried (with a nudge) on the next kernel
- * command, so transient failures and DB resets self-heal. Imported issues land in the
- * read model directly and arrive UNCLAIMED — they surface via `forge issue ready`.
- *
- * @param {object} params
- * @param {string} params.projectRoot
- * @param {string} params.databasePath - kernel DB path (used for the driver config).
- * @param {object} params.broker - an initialized kernel broker to import through.
- * @param {object} params.driver - kernel driver, for the ledger marker read/write.
- * @param {object} [deps] - { fs, warn, now, driver, _fs } seams for tests.
- * @returns {Promise<{action:'migrated'|'nudge'|'skip', reason?:string, inserted?:number}>}
- */
-async function autoMigrateBeadsAtRuntime({ projectRoot, databasePath, broker, driver } = {}, deps = {}) {
-  const fsImpl = deps.fs || fs;
-  const warn = deps.warn || ((msg) => process.stderr.write(`${msg}\n`));
-  const appliedAt = deps.now || new Date().toISOString();
-  const markerDriver = deps.driver || driver;
-  const markerConfig = databasePath ? { databasePath } : {};
-  try {
-    if (!databasePath) {
-      return { action: 'skip', reason: 'no-db-path' };
-    }
-
-    // One-time gate: the import already ran on THIS kernel DB (the marker dies with the
-    // DB, so deleting kernel.sqlite to reset correctly re-triggers the import).
-    if (await importMarkerPresent(markerDriver, markerConfig)) {
-      return { action: 'skip', reason: 'already-imported' };
-    }
-
-    // Only a jsonl export can be imported automatically; anything else is skipped
-    // silently (an empty or export-less store must never trigger a false nudge).
-    if (!detectBeadsJsonlSource(projectRoot, { fs: fsImpl })) {
-      return { action: 'skip', reason: 'no-jsonl' };
-    }
-
-    // Import (idempotent) through the already-initialized broker.
-    let outcome;
-    try {
-      outcome = await autoMigrateBeadsIfPresent(projectRoot, { _broker: broker, _now: deps.now, _fs: deps._fs });
-    } catch (err) {
-      outcome = { migrated: false, result: { success: false, error: err.message } };
-    }
-
-    if (outcome.migrated) {
-      const inserted = outcome.result?.imported?.issues?.inserted ?? 0;
-      const skipped = outcome.result?.imported?.issues?.skipped ?? 0;
-      // Record the marker LAST so a concurrent first run is a benign idempotent skip.
-      await recordImportMarker(markerDriver, markerConfig, appliedAt);
-      if (inserted > 0) {
-        warn(`Forge: imported ${inserted} Beads issue(s) into the Kernel — your issues are here, not lost.`);
-      }
-      return { action: 'migrated', inserted, skipped };
-    }
-
-    // Success-only marker: a failed import records nothing and re-nudges next run,
-    // so a transient failure self-heals once the underlying problem is resolved.
-    const error = outcome.result?.error || outcome.reason || 'unknown error';
-    warn(BEADS_MIGRATE_NUDGE);
-    return { action: 'nudge', reason: 'migrate-failed', error };
-  } catch (err) {
-    // Absolutely never break the command we ride on.
-    return { action: 'skip', reason: 'error', error: err.message };
-  }
-}
-
 module.exports = {
   name: 'migrate',
   description: 'Migrate a Beads issue store into the Forge Kernel with --from beads, '
     + 'or preview the v2→v3 migration (preview only — --dry-run required; applying it is not yet available)',
-  detectBeadsJsonlSource,
-  autoMigrateBeadsIfPresent,
-  autoMigrateBeadsAtRuntime,
   usage: 'forge migrate --from beads [--dry-run] [--source <dir>] [--json]',
   flags: {
     '--from <source>': 'Migration source. Use "beads" to import a Beads issue store into the Kernel.',

package/lib/commands/plan.js

@@ -517,7 +517,12 @@ function currentBranchIssueFromDriver(driver, currentBranch) {
 	if (driver && typeof driver.listWorktrees === 'function') {
 		try {
 			const rows = driver.listWorktrees() || [];
-			const match = rows.find(row => row && row.branch === currentBranch && row.issue_id);
+			// Only an ACTIVE (live) linkage row binds the branch: a superseded/stale
+			// registration for a reused branch name must not trigger a false split-state
+			// conflict against the OLD issue (R4/be18881c). Tolerate a null state for
+			// rows written before the state column was populated.
+			const match = rows.find(row => row && row.branch === currentBranch && row.issue_id
+				&& (row.state === 'active' || row.state == null));
 			if (match) return match.issue_id;
 		} catch {
 			// fall through to branch-name parsing
@@ -553,6 +558,9 @@ async function detectBranchIssueConflict(options, explicitIssueId) {
 async function registerBranchIssueLinkage(options, branch, issueId) {
 	if (!branch || !issueId) return;
 	const cwd = options.projectRoot || process.cwd();
+	// F6 defaultStageWarn pattern: write to stderr so a dropped linkage never
+	// pollutes machine-readable stdout, yet leaves a trace even under FORGE_JSON=1.
+	const warn = options.warn || (message => process.stderr.write(`${message}\n`));
 	await withPlanDriver(options, driver => {
 		if (!driver || typeof driver.registerWorktree !== 'function') return;
 		try {
@@ -566,8 +574,11 @@ async function registerBranchIssueLinkage(options, branch, issueId) {
 				registered_at: new Date().toISOString(),
 				state: 'active',
 			});
-		} catch {
-			// best-effort: linkage failure must not fail plan
+		} catch (error) {
+			// Best-effort: linkage failure must not fail plan, but it must NOT be
+			// silent (R3) — otherwise ship later fail-closes with no signal at plan
+			// time about the dropped branch->issue linkage.
+			warn(`[forge] could not register branch->issue linkage for ${branch} -> ${issueId}: ${error.message}`);
 		}
 	});
 }
@@ -648,7 +659,10 @@ async function createKernelIssue(featureName, researchPath, scope, options = {})
 
 /**
  * Create feature branch
- * Creates and checks out a new git branch following feat/<slug> convention
+ * Creates a new git branch following feat/<slug> convention WITHOUT switching
+ * the shared checkout's HEAD (uses `git branch`, not `git checkout -b`).
+ * Switching HEAD in the shared working tree corrupts concurrent agents
+ * (kernel issue aa14966c); isolated work happens in a dedicated worktree.
  *
  * Security: Uses execFileSync with array args to prevent command injection
  *
@@ -678,14 +692,19 @@ function createFeatureBranch(featureSlug) {
 			execFileSync('git', ['rev-parse', '--verify', branchName], { ...getExecOptions(), stdio: 'pipe' });  // NOSONAR S4036 - hardcoded CLI command, no user input, developer tool context
 			return {
 				success: false,
-				error: `Branch ${branchName} already exists\n\nSwitch to it with: git checkout ${branchName}`,
+				error: `Branch ${branchName} already exists\n\nWork on it in an isolated checkout: forge worktree create ${featureSlug}\n(or, working solo: git switch ${branchName})`,
 			};
 		} catch {
 			// Branch doesn't exist, continue (expected case)
 		}
 
-		// Create and checkout branch
-		execFileSync('git', ['checkout', '-b', branchName], getExecOptions());  // NOSONAR S4036 - hardcoded CLI command, no user input, developer tool context
+		// Create the branch WITHOUT switching the shared checkout's HEAD.
+		// Historically this used `git checkout -b`, which flipped the shared
+		// working tree onto the new branch and corrupted concurrent agents
+		// (kernel issue aa14966c). `git branch` creates the ref at the current
+		// HEAD without touching the working tree; isolated work happens in a
+		// dedicated worktree (`forge worktree create`), never the shared tree.
+		execFileSync('git', ['branch', branchName], getExecOptions());  // NOSONAR S4036 - hardcoded CLI command, no user input, developer tool context
 
 		return {
 			success: true,
@@ -1066,6 +1085,12 @@ async function executePlan(featureName, options = {}) { // NOSONAR S3776
 			beadsIssueId: issue.issueId,
 			branchName: branch.branchName,
 			linked: Boolean(explicitIssueId),
+			// A FRESH branch was created (HEAD did NOT move — aa14966c). Stage
+			// commands resolve the CHECKED-OUT branch, so the user must enter an
+			// isolated checkout on this branch before /dev, or stage state resolves
+			// against the default branch (no linkage → ship dead-ends). When the
+			// branch was reused, HEAD is already on it and /dev works directly.
+			branchCreated: !branch.reused,
 			summary: explicitIssueId
 				? `Plan linked to existing issue ${issue.issueId} (${scope.type} scope)`
 				: `Plan created for ${featureName} (${scope.type} scope)`,
@@ -1104,7 +1129,20 @@ module.exports = {
 		const lines = [`${header}: ${result.summary || result.branchName || featureName}`];
 		if (result.issueId) lines.push(`${issueBackendLabel(result.issueBackend)}: ${result.issueId}`);
 		if (result.branchName) lines.push(`Branch: ${result.branchName}`);
-		if (result.nextCommand) lines.push(`Next: ${result.nextCommand}`);
+		if (result.branchCreated) {
+			// A fresh branch was created but HEAD was NOT switched (aa14966c). Stage
+			// commands (/dev, /validate, /ship) resolve the CHECKED-OUT branch — from
+			// the shared tree that is still the default branch, which has no
+			// branch->issue linkage, so ship would dead-end. Direct the user into an
+			// isolated checkout on the new branch first.
+			const slug = String(result.branchName).replace(/^feat\//, '');
+			lines.push('Next: work on this branch in an isolated checkout (HEAD stays put in the shared tree):');
+			lines.push(`  forge worktree create ${slug}    # concurrent-safe; checks out the existing ${result.branchName}`);
+			lines.push(`  # or, working solo:  git switch ${result.branchName}`);
+			lines.push(`Then run ${result.nextCommand || '/dev'} from that checkout.`);
+		} else if (result.nextCommand) {
+			lines.push(`Next: ${result.nextCommand}`);
+		}
 
 		return {
 			...result,
@@ -1122,4 +1160,6 @@ module.exports = {
 	applyYAGNIFilter,
 	executePlan,
 	issueBackendLabel,
+	registerBranchIssueLinkage,
+	currentBranchIssueFromDriver,
 };

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/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';
 
@@ -110,6 +112,57 @@ async function autoFileBackingIssueForPush(projectRoot, execFn, deps = {}) {
   }
 }
 
+/**
+ * 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
@@ -247,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,
@@ -259,5 +323,7 @@ module.exports = {
 	// Exposed for unit tests; not part of the CLI surface.
 	_internal: {
 		autoFileBackingIssueForPush,
+		maybeArmWatcherAfterPush,
+		resolveOpenPrNumber,
 	},
 };