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

package/.forge/hooks/check-tdd.js

@@ -14,6 +14,70 @@ const fs = require("node:fs");
 const path = require("node:path");
 const readline = require("node:readline");
 
+// ── Config-honest enforcement (issue eda6d866) ──────────────────────────────
+// This pre-commit gate must be INERT when the TDD rail is disabled in
+// .forge/config.yaml. The hook is self-contained (target projects have
+// .forge/hooks/*.js but NOT lib/), so it reads the config directly. `forge gate
+// disable rail.tdd_intent` writes workflow.gates['rail.tdd_intent']; the `full`
+// profile writes top-level rails.tdd_intent — honor either. Missing/unparseable
+// config FAILS TOWARD enforcement (returns true) so a gate the user did not
+// disable is never silently dropped.
+function isTddEnabled(projectRoot) {
+  let raw;
+  try {
+    raw = fs.readFileSync(path.join(projectRoot, ".forge", "config.yaml"), "utf8");
+  } catch {
+    return true; // no config → enforce
+  }
+  if (!raw || !raw.trim()) return true;
+
+  const railDisabled = (config) =>
+    isExplicitlyDisabled(config?.workflow?.gates?.["rail.tdd_intent"]) ||
+    isExplicitlyDisabled(config?.rails?.tdd_intent);
+
+  let YAML;
+  try {
+    YAML = require("yaml");
+  } catch {
+    // The yaml MODULE is genuinely unavailable → conservative raw-text scan for the
+    // disabled block. Parser presence and parse success are split so a MALFORMED file
+    // never reaches this fuzzy scan.
+    return !(rawKeyDisabled(raw, "rail.tdd_intent") || rawKeyDisabled(raw, "tdd_intent"));
+  }
+  try {
+    const parsed = YAML.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return true;
+    return !railDisabled(parsed);
+  } catch {
+    // MALFORMED YAML (module present, parse threw) → FAIL TOWARD ENFORCEMENT (return
+    // true). Never fall to the raw-text scan: a broken file with a `rail.tdd_intent:
+    // enabled: false` fragment must not switch the gate off (issue eda6d866).
+    return true;
+  }
+}
+
+function isExplicitlyDisabled(node) {
+  return Boolean(node) && typeof node === "object" && node.enabled === false;
+}
+
+// Scan raw YAML for a `<key>:` block whose immediate child is `enabled: false`.
+function rawKeyDisabled(raw, key) {
+  const lines = String(raw).split(/\r?\n/);
+  const keyRe = new RegExp(`^(\\s*)"?${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}"?\\s*:\\s*$`);
+  for (let i = 0; i < lines.length; i += 1) {
+    const m = lines[i].match(keyRe);
+    if (!m) continue;
+    const parentIndent = m[1].length;
+    for (let j = i + 1; j < lines.length; j += 1) {
+      if (!lines[j].trim()) continue;
+      const childIndent = lines[j].match(/^\s*/)[0].length;
+      if (childIndent <= parentIndent) break;
+      if (/^\s*enabled\s*:\s*false\s*$/.test(lines[j])) return true;
+    }
+  }
+  return false;
+}
+
 // Get staged files using git diff --cached
 function getStagedFiles() {
   try {
@@ -163,6 +227,12 @@ function promptUser(question, options) {
 
 // Main hook logic
 async function main() {
+  // Project root is two levels up from this installed hook (<root>/.forge/hooks/).
+  // When the TDD rail is disabled in config, the gate is inert — allow the commit.
+  if (!isTddEnabled(path.resolve(__dirname, "..", ".."))) {
+    process.exit(0);
+  }
+
   console.log("🔍 TDD Check: Verifying test coverage for staged files...\n");
 
   const stagedFiles = getStagedFiles();
@@ -236,8 +306,12 @@ async function main() {
   }
 }
 
-// Run with error handling
-main().catch((error) => {
-  console.error("Error in TDD check hook:", error.message);
-  process.exit(1);
-});
+module.exports = { isTddEnabled };
+
+// Run with error handling (only as a script, not when required by tests).
+if (require.main === module) {
+  main().catch((error) => {
+    console.error("Error in TDD check hook:", error.message);
+    process.exit(1);
+  });
+}

package/.forge/hooks/forge-native-hook.js

@@ -32,6 +32,7 @@
  */
 
 const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
 const path = require('node:path');
 
 // Conservative protected-path set, mirroring .forge/protected-paths.yaml categories:
@@ -52,6 +53,174 @@ const PROTECTED_PATTERNS = [
   /(^|\/)(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lock[b]?)$/i,
 ];
 
+// ── Config-honest enforcement ───────────────────────────────────────────────
+// A DISABLED gate/rail in .forge/config.yaml must make its hook genuinely inert
+// (issue eda6d866). These hooks are self-contained (target projects have
+// .forge/hooks/*.js but NOT lib/), so we read + interpret the config here rather
+// than through the resolver. The `yaml` package is a Forge dependency present in
+// any project that ran `forge setup`; when it is somehow absent we degrade to a
+// conservative raw-text scan. Unparseable/missing config FAILS TOWARD enforcement
+// (default ON) so we never silently drop a gate the user did not disable.
+
+/** Load `.forge/config.yaml` into an object, or `{ __raw }` for a text-scan fallback, or null. */
+function loadConfigObject(projectRoot) {
+  let raw;
+  try {
+    raw = fs.readFileSync(path.join(projectRoot, '.forge', 'config.yaml'), 'utf8');
+  } catch {
+    return null; // no config file → caller defaults to enforcement ON
+  }
+  if (!raw || !raw.trim()) return {};
+  let YAML;
+  try {
+    YAML = require('yaml');
+  } catch {
+    // The yaml MODULE is genuinely unavailable → degrade to a conservative raw-text
+    // scan (the only case that keeps { __raw }). Parser presence and parse success are
+    // deliberately separated so a MALFORMED file never reaches the fuzzy scan below.
+    return { __raw: raw };
+  }
+  try {
+    const parsed = YAML.parse(raw);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    // MALFORMED YAML (module present, parse threw) → FAIL TOWARD ENFORCEMENT. Return {}
+    // so resolveEnforcement defaults to TDD ON + built-in protected paths. We must NOT
+    // fall through to the raw-text scan: a broken file containing a `rail.tdd_intent:
+    // enabled: false` fragment could otherwise switch enforcement OFF (issue eda6d866).
+    return {};
+  }
+}
+
+/** A primitive is "disabled" only when its `enabled` is explicitly boolean false. */
+function isExplicitlyDisabled(node) {
+  return Boolean(node) && typeof node === 'object' && node.enabled === false;
+}
+
+// Overly-broad patterns the runtime graph rejects (lib/core/runtime-graph.js
+// validateProtectedPaths). Kept in sync here because this hook is self-contained
+// and cannot import from lib/.
+const OVERLY_BROAD_PROTECTED_PATTERNS = ['*', '**', '**/*', '.', './', '/'];
+
+/**
+ * Validate a config-supplied protectedPaths list with the SAME rules the runtime
+ * graph enforces: every entry must be a non-empty string and not an overly-broad
+ * pattern. A list with ANY invalid entry is rejected WHOLESALE (returns null →
+ * caller falls back to the built-in protected set), so an invalid or overly-broad
+ * config can never become authoritative and WEAKEN protection — it fails toward
+ * enforcement, matching the rest of this hook's fail-safe stance (issue eda6d866).
+ * @returns {string[]|null} validated list (may be empty = deliberately inert), or
+ *   null when the list is absent/invalid.
+ */
+function validateConfiguredProtectedPaths(list) {
+  if (!Array.isArray(list)) return null;
+  const validated = [];
+  for (const entry of list) {
+    if (typeof entry !== 'string' || entry.trim() === '') return null;
+    const pattern = entry.trim();
+    if (OVERLY_BROAD_PROTECTED_PATTERNS.includes(pattern)) return null;
+    validated.push(pattern);
+  }
+  return validated;
+}
+
+/** Scan raw YAML for a `<key>:` block whose immediate child is `enabled: false`. */
+function rawKeyDisabled(raw, key) {
+  const lines = String(raw).split(/\r?\n/);
+  const keyRe = new RegExp(`^(\\s*)"?${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}"?\\s*:\\s*$`);
+  for (let i = 0; i < lines.length; i += 1) {
+    const m = lines[i].match(keyRe);
+    if (!m) continue;
+    const parentIndent = m[1].length;
+    for (let j = i + 1; j < lines.length; j += 1) {
+      if (!lines[j].trim()) continue;
+      const childIndent = lines[j].match(/^\s*/)[0].length;
+      if (childIndent <= parentIndent) break; // left the block
+      if (/^\s*enabled\s*:\s*false\s*$/.test(lines[j])) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Resolve the enforcement state the installed hooks must honor.
+ * @returns {{ tddEnabled: boolean, protectedPaths: string[]|null }}
+ *   tddEnabled     — false only when rail.tdd_intent is explicitly disabled.
+ *   protectedPaths — the configured list (may be []), or null when unset (→ built-in set).
+ */
+function resolveEnforcement(projectRoot) {
+  const config = loadConfigObject(projectRoot);
+  if (!config) return { tddEnabled: true, protectedPaths: null };
+
+  let tddDisabled;
+  let protectedPaths = null;
+  if (config.__raw) {
+    tddDisabled = rawKeyDisabled(config.__raw, 'rail.tdd_intent') || rawKeyDisabled(config.__raw, 'tdd_intent');
+    if (/^\s*protectedPaths\s*:\s*\[\s*\]\s*$/m.test(config.__raw)) protectedPaths = [];
+  } else {
+    // `forge gate disable` writes workflow.gates['rail.tdd_intent']; the `full`
+    // profile writes top-level rails.tdd_intent. Honor either shape.
+    const gates = config.workflow && config.workflow.gates;
+    const rails = config.rails;
+    tddDisabled = isExplicitlyDisabled(gates && gates['rail.tdd_intent'])
+      || isExplicitlyDisabled(rails && rails.tdd_intent);
+    // Validate before overriding built-in protection: a bad/overly-broad list must
+    // fall back to the built-in set (null), never become authoritative (T2).
+    protectedPaths = validateConfiguredProtectedPaths(config.protectedPaths);
+  }
+  return { tddEnabled: !tddDisabled, protectedPaths };
+}
+
+/**
+ * The SINGLE resolved predicate each hook gates on — flag-agnostic on purpose.
+ * Whatever config flag ultimately governs an enforcement kind resolves inside
+ * resolveEnforcement(); callers ask only "is this active?". This is the one place
+ * the TDD off-switch is read, so a future flag change lands here with no rework.
+ * @param {'tdd'|'protected-path'} kind
+ */
+function isEnforcementActive(kind, projectRoot) {
+  const { tddEnabled, protectedPaths } = resolveEnforcement(projectRoot);
+  if (kind === 'tdd') return tddEnabled;
+  if (kind === 'protected-path') return protectedPaths === null || protectedPaths.length > 0;
+  return true;
+}
+
+// Translate a config protectedPaths entry (a path or glob like `.github/workflows/**`)
+// into an anchored matcher. `**` spans path separators, `*` stays within one segment.
+function globToRegExp(pattern) {
+  const norm = normalize(pattern);
+  let re = '';
+  for (let i = 0; i < norm.length; i += 1) {
+    const c = norm[i];
+    if (c === '*') {
+      if (norm[i + 1] === '*') { re += '.*'; i += 1; if (norm[i + 1] === '/') i += 1; }
+      else re += '[^/]*';
+    } else if ('\\^$.|?+()[]{}'.includes(c)) {
+      re += `\\${c}`;
+    } else {
+      re += c;
+    }
+  }
+  return new RegExp(`(^|/)${re}(/|$)`);
+}
+
+/**
+ * Build the protected-path matcher from resolved config (config is the source of
+ * truth — the hardcoded PROTECTED_PATTERNS set is only the fallback when config
+ * omits protectedPaths entirely, so no gate is silently dropped):
+ *   null → unset → built-in default set (fail toward enforcement / back-compat)
+ *   []   → explicitly empty → nothing protected (inert)
+ *   list → protect exactly those paths/globs
+ */
+function buildProtectedMatcher(protectedPaths) {
+  if (protectedPaths === null) {
+    return p => Boolean(p) && PROTECTED_PATTERNS.some(re => re.test(normalize(p)));
+  }
+  if (protectedPaths.length === 0) return () => false;
+  const regexes = protectedPaths.map(globToRegExp);
+  return p => Boolean(p) && regexes.some(re => re.test(normalize(p)));
+}
+
 /** Parse `--intent <id> --harness <id>` from an argv slice. */
 function parseArgs(argv) {
   const out = { intent: null, harness: null };
@@ -84,7 +253,7 @@ function normalize(p) {
   return String(p).replace(/\\/g, '/').replace(/^\.\//, '');
 }
 
-/** True when a path falls inside Forge's protected set. */
+/** True when a path falls inside Forge's built-in protected set (the fallback matcher). */
 function isProtectedPath(p) {
   if (!p) return false;
   const n = normalize(p);
@@ -105,13 +274,13 @@ const WRITE_INTENT_RE = /(^|[\s;|&(])(rm|mv|cp|tee|truncate|chmod|chown|ln|sed|p
  * (rm/mv/sed/tee/redirection/...), then (2) token-scan (split on whitespace +
  * shell operators, strip quotes) for a protected path. Never throws.
  */
-function commandTouchesProtectedPath(command) {
+function commandTouchesProtectedPath(command, isProtected = isProtectedPath) {
   if (typeof command !== 'string' || !command) return false;
   if (!WRITE_INTENT_RE.test(command)) return false;
   const tokens = command.split(/[\s;|&<>()]+/);
   for (const raw of tokens) {
     const token = raw.replace(/^["']+|["']+$/g, '');
-    if (token && !token.startsWith('-') && isProtectedPath(token)) return true;
+    if (token && !token.startsWith('-') && isProtected(token)) return true;
   }
   return false;
 }
@@ -133,14 +302,22 @@ function runInstalledTddCheck() {
   }
 }
 
+// Fully-ON default keeps back-compat: callers that pass no `enforcement` (and the
+// existing test suite) get the original always-enforce behavior.
+const ENFORCEMENT_ON = Object.freeze({ tddEnabled: true, protectedPaths: null });
+
 /**
- * Core enforcement decision. `runTddCheck` is injectable for deterministic tests.
+ * Core enforcement decision. `runTddCheck` is injectable for deterministic tests;
+ * `enforcement` (from resolveEnforcement) makes a DISABLED gate/rail inert.
  * @returns {{ decision: 'allow'|'deny', reason?: string }}
  */
-function decide({ intent, input, runTddCheck = runInstalledTddCheck }) {
+function decide({ intent, input, runTddCheck = runInstalledTddCheck, enforcement = ENFORCEMENT_ON }) {
   if (intent === 'protected-path') {
+    // Config is the source of truth: matcher is built from the resolved
+    // protectedPaths list (empty → inert; unset → built-in fallback set).
+    const matchesProtected = buildProtectedMatcher(enforcement.protectedPaths);
     const target = extractPath(input);
-    if (isProtectedPath(target)) {
+    if (matchesProtected(target)) {
       return {
         decision: 'deny',
         reason: `Forge-protected path '${normalize(target)}' — edit it through the owning Forge CLI/skill, not a raw write.`,
@@ -151,7 +328,7 @@ function decide({ intent, input, runTddCheck = runInstalledTddCheck }) {
     // so the deny-capable shell surface actually protects instead of no-oping.
     if (!target) {
       const command = extractCommand(input);
-      if (commandTouchesProtectedPath(command)) {
+      if (commandTouchesProtectedPath(command, matchesProtected)) {
         return {
           decision: 'deny',
           reason: 'Shell command writes to a Forge-protected path — use the owning Forge CLI/skill instead.',
@@ -162,6 +339,8 @@ function decide({ intent, input, runTddCheck = runInstalledTddCheck }) {
   }
 
   if (intent === 'tdd-gate') {
+    // TDD rail disabled in config → inert: never run the check, never block.
+    if (!enforcement.tddEnabled) return { decision: 'allow' };
     const command = extractCommand(input);
     if (!isGitCommit(command)) return { decision: 'allow' };
     const code = runTddCheck();
@@ -222,7 +401,10 @@ function readStdin() {
 function main() {
   const { intent, harness } = parseArgs(process.argv.slice(2));
   const input = readStdin();
-  const decision = decide({ intent, input });
+  // Project root is two levels up from this installed hook (<root>/.forge/hooks/),
+  // so enforcement resolves against the project's config regardless of cwd.
+  const enforcement = resolveEnforcement(path.resolve(__dirname, '..', '..'));
+  const decision = decide({ intent, input, enforcement });
   const output = formatOutput(harness || 'claude', decision);
   if (output) process.stdout.write(output);
   // Exit 0 always: the decision travels in the JSON body, not the exit code, so a
@@ -232,6 +414,10 @@ function main() {
 
 module.exports = {
   PROTECTED_PATTERNS,
+  resolveEnforcement,
+  isEnforcementActive,
+  globToRegExp,
+  buildProtectedMatcher,
   parseArgs,
   extractPath,
   extractCommand,

package/AGENTS.md

@@ -150,6 +150,7 @@ This project uses the **Professional Git Workflow** with Lefthook for automated
 - Blocks commits if source code modified without test files
 - Offers guided recovery (add tests now, skip with tech debt tracking, emergency override)
 - No AI decision required - automatic validation
+- **Strong default, not a hard floor.** The TDD gate is the default-ON `rail.tdd_intent` rail; turn it off with `forge gate disable rail.tdd_intent` (the `minimal` adoption profile ships it off). The installed hooks read the resolved config at run time, so a disabled rail makes them genuinely inert — enforcement honestly follows your config.
 
 **Pre-push hook validates tests:**
 - Branch protection: blocks direct push to `main`/`master`

package/CHANGELOG.md

@@ -9,6 +9,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.0-beta.3] - 2026-07-17
+
+The **adoption-unblocking wave** — the changes beta testers hit on their very first real session. `forge ship`, the hook-enforcement verdict, and `forge worktree create` no longer dead-end a fresh or in-flight branch, and the PR shepherd now arms itself for any agent. Every change below was adversarially reviewed before merge.
+
+### Fixed
+
+- **`forge ship` / `forge review` no longer hard-fail on a fresh or in-flight branch (B1).** They previously threw `Stage ship requires authoritative workflow state` whenever no `/plan → /dev → /validate → /ship` history had been walked — blocking the three most common adoption paths: a fresh setup, an in-flight branch, and a manual commit. The stage gate now degrades to a loud stderr warning and seeds stage history in the kernel, so ship works incrementally and future gating gets real data. The rework/contradiction guard (e.g. `validate` started-but-not-done) stays **fail-closed**, and `FORGE_STAGE_GATE=strict` restores the legacy hard block. (#413)
+- **`forge setup` / `forge init --profile minimal` report hook enforcement honestly.** A deliberately-disabled TDD gate no longer prints `✓ Git hook enforcement active` or exits `1` with a `TDD ENFORCEMENT IS NOT ACTIVE` banner — the human-facing verdict and exit code now honor the resolved config (the hook scripts already honored it at run time; this closes the reporting/exit half). A disabled gate reports as intentionally inert with the re-enable command; a corrupt config still fails toward enforcement. (#414, #399)
+- **`forge worktree create` bases new branches on the default branch, not the current checkout (B2).** A worktree created while on a WIP branch previously forked from the current HEAD and silently inherited unrelated commits. New worktrees now fork from the repository default branch (`origin/<default>` when the remote ref exists, else the local default); a new `--base <ref>` flag overrides it (invalid refs error and create nothing), and `create` prints the base it used so the fork point is never silent. (#415)
+- **`forge plan` no longer moves the shared checkout's HEAD.** Creating the feature branch during planning switched the shared working checkout, colliding with parallel work; it now creates the branch without switching HEAD. (#396)
+- **CI and grounding hardening.** Closed a Windows `EBUSY` by closing the kernel driver after context-event I/O (#411); removed an invalid `pull_request_review_thread` Actions trigger from the PR monitor (#404); stopped the pr-monitor red-X and auto-regenerated the D20 kill-list (#394); and cleared five residual B1 stage-state/worktree-linkage rows (#393). The kernel-driver close/ownership invariant is now regression-tested (#412).
+
+### Added
+
+- **Agent-agnostic auto-shepherd PR monitor.** The PR watcher now arms itself on any open PR (`forge push` + `watch --adopt`), gated on the default-ON `rail.auto_shepherd` rail so **any** harness gets PR tracking without a per-agent monitor (#408, #407). It surfaces PR-monitor events into each turn via shepherd-events hooks (#409), lands an actionable `pr-verdict:*` label on the PR (#403), and takes Tier-2 **safe** auto-actions — update-branch when behind, re-run a flaky required check (#406).
+- **Grounding read-first gate.** A P1 **fail-closed** `gate.read_first` blocks a claim about a file the agent has not read. (#410)
+- **Unified command surface — noun verbs + aliases.** Declarative command-alias infrastructure (#401), `forge memory` shortcuts with a passthrough fix (#402), and a `forge pr` noun (`ship`/`preflight`/`shepherd`/`merge`) with gate docs (#405) — the CLI now groups by how people conventionally use it, aliases preserved.
+- **Memory capture-on-exit + unified `forge memory`.** Memory commands are consolidated under `forge memory` with typed notes (#392), and a PreCompact/Stop hook plus `--session-summary` captures session memory on exit so nothing is lost to a compaction. (#397)
+- **Global-plugin front door + lazy `.forge` home.** A global activation entry point that creates the `.forge` home lazily on first use. (#400)
+- **Guided 0.0.10 → current upgrade.** `forge upgrade` walks the breaking Beads → Kernel upgrade from 0.0.10 and nudges the issue-path migration. (#398)
+- **Consolidated opt-in Beads → Kernel migrator.** A single explicit-only migrator with an honest field-gap report. (#391)
+
+### Changed
+
+- **TypeScript dev dependency bumped 5.4.5 → 7.0.2** (dev-deps group; no runtime change). (#371)
+- Install docs now point at `forge-workflow@beta` so users land on the current prerelease. (#395)
+- Bumped the GitHub Actions dependency group (3 updates). (#390)
+
 ## [0.1.0-beta.2] - 2026-07-15
 
 The **beta-blocker hardening wave** — Forge's advertised loop now composes end to end, its quality gates fail closed, its control surfaces describe themselves honestly, and the runtime is Beads-free. Every change below was adversarially reviewed before merge. (v0.1.0-beta.1 was tagged but never reached npm — its publish token had expired; this release switches to OIDC Trusted Publishing and is the first npm beta.)

package/QUICKSTART.md

@@ -14,12 +14,16 @@ This guide gets Forge installed and visible to an AI coding agent without assumi
 
 ```bash
 # Bun
-bun add -D forge-workflow
+bun add -D forge-workflow@beta
 
 # npm
-npm install --save-dev forge-workflow
+npm install --save-dev forge-workflow@beta
 ```
 
+> **Note:** the current release is a **prerelease** published under the `beta`
+> dist-tag, so install with `@beta`. A bare `forge-workflow` resolves to the
+> older `latest` (stable) version.
+
 You can also run one-off commands with `bunx forge ...` (or `npx forge ...`).
 
 Terms used below:

package/README.md

@@ -188,7 +188,9 @@ actually works, and update it as you grow.
 
 ```bash
 # Add to your project
-bun add -D forge-workflow          # or: npm install --save-dev forge-workflow
+bun add -D forge-workflow@beta     # or: npm install --save-dev forge-workflow@beta
+# The current release is a prerelease under the `beta` dist-tag; a bare
+# `forge-workflow` resolves to the older stable `latest`.
 
 # Install for your agent(s) and configure the workflow
 bunx forge setup --agents claude --yes

package/bin/forge.js

@@ -60,10 +60,21 @@ const {
 } = require('../lib/docs-command');
 const { resetSoft, resetHard, reinstall } = require('../lib/reset');
 const { loadCommands, executeCommand } = require('../lib/commands/_registry');
+const {
+  isAlias,
+  isHiddenAlias,
+  isVisibleAlias,
+  resolveAlias,
+  resolveDispatch,
+  maybeWarnDeprecation,
+  passthroughAliasNames,
+  visibleAliasNames,
+} = require('../lib/commands/_aliases');
 const { resolveCommandOpts } = require('../lib/commands/_resolve-command-opts');
 const { getPackageRoot } = require('../lib/package-root');
 const { enforceStageEntry } = require('../lib/workflow/enforce-stage');
 const { normalizeStageId } = require('../lib/workflow/stages');
+const { firstPositionalIndex } = require('../lib/global-flags');
 
 // Load enhanced onboarding modules (static relative requires — bundleable)
 const contextMerge = require('../lib/context-merge');
@@ -2315,16 +2326,12 @@ async function _interactiveSetup() {
 }
 
 // Parse CLI flags
-// Issue command aliases hidden from `forge --help`: the bare passthroughs that
-// duplicate `forge issue <sub>` plus the plural `issues`. They stay registered and
-// routable (back-compat), but are omitted from help so `forge issue` reads as the
-// single canonical issue surface (kernel issue 450c6e34). The canonical `issue` is
-// deliberately NOT listed here — it stays documented.
-const ISSUE_ALIAS_COMMANDS = [
-  'create', 'update', 'claim', 'close', 'show', 'list',
-  'ready', 'blocked', 'stale', 'orphans', 'lint', 'claims', 'issues',
-];
-
+// The curated back-compat alias allowlist (formerly the inline
+// ISSUE_ALIAS_COMMANDS array) now lives in lib/commands/_aliases.js as the single
+// declarative source of truth. `aliasNames()` returns the bare verbs that stay
+// registered + routable but are hidden from `forge --help` (kernel issue 450c6e34),
+// so `forge issue` reads as the single canonical issue surface. The canonical
+// `issue` is deliberately not an alias — it stays documented.
 function parseFlags() {
   const flags = {
     quick: false,
@@ -2349,8 +2356,11 @@ function parseFlags() {
 
   // Issue passthrough commands delegate all flags to bd.
   // Skip global parsing so flags like --type, -p, --help reach the handler intact.
-  // Canonical `issue` plus the hidden back-compat aliases (single source of truth).
-  const issuePassthroughCommands = [...ISSUE_ALIAS_COMMANDS, 'issue'];
+  // Canonical `issue` plus the ISSUE-canonical back-compat aliases only. Non-issue
+  // aliases (e.g. the memory shortcuts remember/recall/insights) are excluded so
+  // their global flags still parse exactly as their standalone commands' did —
+  // keeping bare `recall -p <dir>` / `recall --help` byte-identical.
+  const issuePassthroughCommands = [...passthroughAliasNames(), 'issue'];
   if (issuePassthroughCommands.includes(args[0])) {
     return flags;
   }
@@ -2610,15 +2620,30 @@ function showHelp() {
   console.log('  Run `forge init --help` for all profile/classification/harness flags.');
   console.log('');
 
+  // Shortcuts block: VISIBLE back-compat aliases for a canonical `<noun> <sub>`
+  // form (e.g. `remember` -> `forge memory add`). The bare verb keeps working and
+  // is documented here; the noun form is canonical. Rendered as its own block ABOVE
+  // "Additional commands" (and trimmed from that enumeration below) so the noun
+  // surface reads clean.
+  const shortcutNames = visibleAliasNames();
+  if (shortcutNames.length > 0) {
+    console.log('Shortcuts (bare aliases for canonical noun subcommands):');
+    const shortcutWidth = Math.max(...shortcutNames.map(name => name.length));
+    for (const name of shortcutNames) {
+      console.log(`  ${name.padEnd(shortcutWidth)}  -> forge ${resolveAlias(name).canonical}`);
+    }
+    console.log('');
+  }
+
   // Append auto-discovered registry commands. Hidden issue aliases (the bare
   // passthroughs + plural `issues`, plus any command self-declaring `hidden: true`)
-  // still route and execute, but are trimmed from this enumeration so `forge issue`
-  // reads as the single canonical issue surface. This registry instance is loaded
-  // solely to render help, so deleting from its Map only affects the printed list —
-  // command dispatch (main) uses a separate registry and is unaffected.
+  // AND the visible noun shortcuts rendered above are trimmed from this enumeration
+  // so the canonical noun surface reads clean; both remain routable. This registry
+  // instance is loaded solely to render help, so deleting from its Map only affects
+  // the printed list — command dispatch (main) uses a separate registry.
   const helpRegistry = loadCommands(path.join(__dirname, '..', 'lib', 'commands'));
   for (const [name, cmd] of [...helpRegistry.commands]) {
-    if (ISSUE_ALIAS_COMMANDS.includes(name) || cmd.hidden === true) {
+    if (isHiddenAlias(name) || isVisibleAlias(name) || cmd.hidden === true) {
       helpRegistry.commands.delete(name);
     }
   }
@@ -3945,7 +3970,7 @@ async function handleExternalServices(skipExternal, selectedAgents) {
 }
 
 async function main() {
-  const command = args[0];
+  let command = args[0];
   const flags = parseFlags();
   const suppressJsonIntrospectionOutput = ['options', 'explain'].includes(command) && args.includes('--json');
   const suppressCommandJsonOutput = args.includes('--json');
@@ -4032,6 +4057,52 @@ async function main() {
     }
   }
 
+  // Back-compat alias handling (lib/commands/_aliases.js, the single declarative
+  // source of truth generalised from the former ISSUE_ALIAS_COMMANDS array). Emit
+  // an opt-in deprecation hint (stderr only, gated on FORGE_DEPRECATION_WARNINGS +
+  // the alias being marked deprecated — never on stdout, so `--json` stays clean),
+  // then resolve any bare alias whose name is NOT itself a registered command to
+  // its canonical `<noun> <sub>` handler. For P0 every alias is also a registered
+  // command file and none are deprecated, so nothing warns and nothing is
+  // rewritten — dispatch stays byte-identical. Registered commands skip the
+  // rewrite via the first clause; this activates only when a later phase folds a
+  // bare verb into a noun handler.
+  maybeWarnDeprecation(command);
+  let dispatchArgv = args;
+  if (!registry.commands.has(command) && isAlias(command)) {
+    const resolved = resolveDispatch(command, args, (name) => registry.commands.has(name));
+    command = resolved.command;
+    dispatchArgv = resolved.args;
+  }
+
+  // A workflow stage reached through its canonical noun form (e.g. `pr ship`,
+  // whose bare alias `ship` IS a stage) must dispatch through the SAME top-level
+  // stage path as the bare verb — stage-entry enforcement, kernel stage-run
+  // recording, and ensureForgeHome all key on the stage token, which sits at the
+  // subcommand position under a noun. Rewrite `<noun> <stage> [args]` to the
+  // top-level `<stage> [args]` so behavior is byte-identical to the bare stage
+  // alias. Detected precisely via the declarative alias map: the subcommand is a
+  // stage AND its bare alias's canonical is exactly `<command> <sub>` (so only a
+  // genuine noun→stage form matches; non-stage pr/gate subcommands route via
+  // their noun handler as usual). Only `pr ship` matches today.
+  //
+  // The stage token is located as the first POSITIONAL after the noun (scanning
+  // past any global flags and their values), so `forge pr --path /tmp ship ...`
+  // shares the same stage path as `forge pr ship ...` instead of falling through
+  // to pr.handler and missing stage-entry enforcement. Intervening global flags
+  // are preserved into the rewritten argv so the stage handler still sees them.
+  const stageIdx = firstPositionalIndex(dispatchArgv, 1);
+  const nounSub = stageIdx >= 0 ? dispatchArgv[stageIdx] : undefined;
+  if (nounSub && normalizeStageId(nounSub) && registry.commands.has(nounSub)) {
+    const bareAlias = resolveAlias(nounSub);
+    if (bareAlias && bareAlias.canonical === `${command} ${nounSub}`) {
+      command = nounSub;
+      // Drop only the consumed stage token (the noun at index 0 is dropped by the
+      // registry dispatch's own `.slice(1)`); keep the intervening global flags.
+      dispatchArgv = [nounSub, ...dispatchArgv.slice(1, stageIdx), ...dispatchArgv.slice(stageIdx + 1)];
+    }
+  }
+
   // Registry command dispatch — auto-discovered commands take priority
   if (registry.commands.has(command)) {
     try {
@@ -4041,7 +4112,7 @@ async function main() {
       // also assembles the driver + migrated broker (B1/B2).
       const { commandOpts, args: dispatchArgs } = await resolveCommandOpts(
         command,
-        args.slice(1),
+        dispatchArgv.slice(1),
         { env: process.env, projectRoot },
       );
       const result = await executeCommand(

package/docs/guides/SETUP.md

@@ -12,9 +12,12 @@ This guide covers supported Forge adoption paths. Use [Quickstart](../../QUICKST
 ## Install
 
 ```bash
-bun add -D forge-workflow
+bun add -D forge-workflow@beta
 ```
 
+> The current release is a prerelease under the `beta` dist-tag — install with
+> `@beta`. A bare `forge-workflow` resolves to the older stable `latest`.
+
 The package exposes `forge`, `forge-workflow`, and `forge-preflight`.
 
 `install.sh` is a thin bootstrapper. It installs or invokes `forge-workflow` and delegates setup to the package; it is not a separate implementation of setup behavior.

package/docs/guides/SUPPORT.md

@@ -108,6 +108,11 @@ Create isolated work:
 forge worktree create <slug> --branch <branch-name>
 ```
 
+The new branch is forked from the repository's default branch (`origin/<default>`
+when present, else the local default), not the current checkout — so a worktree
+made from a WIP branch does not inherit unrelated commits. Override with
+`--base <ref>` to fork from a specific ref; `create` prints the base it used.
+
 Remove it:
 
 ```bash