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

package/docs/reference/COMMANDS.md

@@ -105,12 +105,21 @@ forge sync
 
 ```bash
 forge worktree create <slug> --branch <branch-name>
+forge worktree create <slug> --base <ref>
 forge worktree remove <slug>
 forge clean --dry-run
 ```
 
 Slugs must not contain `..`, `/`, or `\`.
 
+A new worktree's branch is forked from the repository's **default branch**
+(`origin/<default>` when the remote ref exists, else the local default) — **not**
+the checkout's current branch/HEAD — so a worktree created from a WIP branch never
+silently inherits unrelated commits. Pass `--base <ref>` to fork from a specific
+ref instead; an invalid `--base` errors and creates nothing. `create` prints the
+base it used (e.g. `Created worktree <path> on <branch> (based on origin/main).`)
+so the fork point is never silent.
+
 ## Adapters
 
 ```bash

package/docs/reference/shepherd.md

@@ -67,6 +67,43 @@ up from there.
 a `/loop`) that re-invokes the bounded pass with a debounce of at least 60
 seconds and cancel-in-progress. The shepherd itself never waits in-process.
 
+## Auto-start on ship (`rail.auto_shepherd`)
+
+`forge shepherd watch <pr>` is the constant, self-stopping local monitor loop
+(≈60 s jittered cadence; appends events to the per-PR NDJSON journal under
+`.forge/pr-monitor/<repo>-<pr>/`; self-stops on `PR_MERGED`/`PR_CLOSED`). On a
+successful `forge ship`, the new PR's watcher is **auto-started detached** so a
+shipped PR is tended without a manual trigger. The spawn is best-effort and
+**never fails ship** (a spawn or config-read error degrades to "not started"),
+and it is idempotent — the watch-lifecycle PID/journal lock prevents a second
+watcher for the same PR.
+
+This auto-start is governed by the default-ON, unlocked **`rail.auto_shepherd`**
+rail. Opt out with `forge gate disable rail.auto_shepherd` (re-enable with
+`forge gate enable rail.auto_shepherd`); when disabled, `forge ship` skips the
+auto-start. This keeps the behavior honestly toggleable through the same config
+surface as every other rail.
+
+## Surfacing events back to the agent (`forge hooks shepherd-events`)
+
+The constant watch loop is the PRODUCER: it writes per-PR NDJSON journals under
+`.forge/pr-monitor/<repo>-<pr>/`, while the `forge shepherd events <pr> --since
+<seq>` pull surface reads existing records back from them. But a journal only
+helps if the working agent sees it. `forge hooks shepherd-events` is the thin,
+agent-agnostic CONSUMER: it reads the NEW budget events across all open-PR journals
+since a persisted per-PR **consumer cursor** (kept in `consumer.cursor`, distinct
+from the watcher's snapshot), renders a **compact, capped** summary of the
+actionable transitions only — verdict changes, failed checks, new review threads,
+merged/closed — then advances the cursor so nothing re-surfaces.
+
+For Claude Code this is wired as a **UserPromptSubmit** context hook (the honest
+capability matrix: only Claude exposes that additionalContext surface; Cursor /
+Codex / Hermes carry an explicit skip reason). It is **additive and FAIL-OPEN** —
+a missing/empty digest, a corrupt journal, or no `.forge/pr-monitor` at all never
+blocks a prompt — and it reads the user's own local journal only: it never
+injects into stdin and never drives the agent. Any other harness can call the
+same verb (or `forge shepherd events`) on its own cadence.
+
 ## Terminal states
 
 | State         | Meaning |
@@ -111,5 +148,8 @@ seconds and cancel-in-progress. The shepherd itself never waits in-process.
 
 ## State
 
-Progress is durable in GitHub PR comments and labels plus `git`. There is no
-separate local state store.
+Progress is durable in GitHub PR comments and labels plus `git`. The one local
+store is the constant monitor's per-PR journal under
+`.forge/pr-monitor/<repo>-<pr>/` (the append-only `events.ndjson` + snapshot and
+consumer cursors) — the delivery/replay surface for `forge shepherd watch` and
+`events --since`. The bounded shepherd pass itself keeps no separate local state.

package/lib/activation/ensure-forge-home.js

@@ -0,0 +1,135 @@
+'use strict';
+
+/**
+ * Lazy `.forge/` home creation (activation foundation).
+ *
+ * Discovery ≠ initialization. The global Forge plugin (SessionStart hook +
+ * `activation` skill) must create NOTHING in a user's repo. The FIRST verb that
+ * performs a real MUTATION (e.g. `forge claim`, `forge create`, `forge
+ * remember`) is what lazily materializes the bare-minimum `.forge/` skeleton.
+ * Read-only verbs (`ready`, `show`, `status`, `recap`, …) never call this, so a
+ * bare repo stays untouched until the user actually changes state.
+ *
+ * "Bare-minimum" here is strictly LESS than `forge init --minimal`: this writes
+ * ONLY `.forge/config.yaml` with every gate disabled (the `minimal` adoption
+ * profile). It installs NO git hooks, NO lefthook.yml, NO protected-paths
+ * manifest, NO `.mcp.json`, and NO scripts tree — those remain the opt-in
+ * payload of `forge setup`, never forced. Progressive growth: heavier slices
+ * initialize themselves on first use.
+ *
+ * @module activation/ensure-forge-home
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { renderAdoptionConfigYaml } = require('../adoption-profiles');
+
+/**
+ * Core verbs that MUTATE project state and therefore need `.forge/` to exist.
+ *
+ * Deliberately excludes `init`/`setup` — they own `.forge/` creation with their
+ * own (richer) logic, and pre-creating a minimal config would trip their
+ * no-clobber guard. Also excludes every read-only verb, so those write nothing.
+ *
+ * Deliberately EXCLUDES `gate` and `stage`: each has read-only subcommands
+ * (`gate status`/`gate check`, `stage --list`/`--current`) that must not create
+ * `.forge/` — a verb-level trigger would violate the foundation's own
+ * "read-only writes nothing" invariant. Their genuinely-mutating forms
+ * self-manage without ensureForgeHome: `gate enable|disable` and `role` write
+ * via the config writer (which creates `.forge/config.yaml` if absent), while
+ * `gate approve|reject` and `stage --start|--complete` write kernel events/runs
+ * through the broker (which lazily creates its own store). Subcommand-level
+ * granularity is deferred; excluding the whole verb is the correct, safe default
+ * because the read-only forms are the common case. `role` is retained: it has NO
+ * read-only form (every valid invocation writes config), so it violates nothing.
+ *
+ * A command module may override membership by exporting `mutating: true|false`;
+ * this Set is the default classification for the foundation.
+ */
+const MUTATING_VERBS = new Set([
+  'claim',
+  'close',
+  'create',
+  'comment',
+  'update',
+  'add',
+  'new',
+  'remember',
+  'role',
+  'patch',
+]);
+
+/**
+ * Decide whether a verb should lazily ensure the `.forge/` home.
+ *
+ * A command module's explicit `mutating` boolean wins; otherwise fall back to
+ * the default {@link MUTATING_VERBS} classification.
+ *
+ * @param {string} name - Command/verb name being dispatched.
+ * @param {object} [command] - The resolved command module (may declare `mutating`).
+ * @returns {boolean}
+ */
+function isMutatingVerb(name, command) {
+  if (command && typeof command === 'object' && typeof command.mutating === 'boolean') {
+    return command.mutating;
+  }
+  return MUTATING_VERBS.has(name);
+}
+
+/**
+ * Render the bare-minimum, gates-disabled config body.
+ *
+ * Reuses the canonical `minimal` adoption profile so the produced YAML is
+ * schema-valid and identical in spirit to `forge init --minimal` (minus the
+ * hooks/protected-paths side effects). Overridable via `deps.renderConfig` for
+ * tests that don't want to depend on the profile renderer.
+ *
+ * @param {object} [deps]
+ * @returns {string} config.yaml contents
+ */
+function renderMinimalConfig(deps = {}) {
+  const render = deps.renderConfig || (() => renderAdoptionConfigYaml('minimal'));
+  return render();
+}
+
+/**
+ * Idempotently create the bare-minimum `.forge/` skeleton for a mutating verb.
+ *
+ * No-clobber by construction: if `.forge/` already exists (inited repo, or a
+ * partially-created home), this is a NO-OP and never touches the user's files.
+ * The kernel/issue store (`.forge/kernel/…`) is created lazily by the broker on
+ * the mutating verb itself — this function only guarantees the config skeleton.
+ *
+ * @param {string} [projectRoot=process.cwd()] - Repo root to initialize.
+ * @param {object} [deps] - Injectable seams: `fs`, `renderConfig`.
+ * @returns {{ created: boolean, reason?: string, configPath: string }}
+ */
+function ensureForgeHome(projectRoot = process.cwd(), deps = {}) {
+  const fsImpl = deps.fs || fs;
+  const forgeDir = path.join(projectRoot, '.forge');
+  const configPath = path.join(forgeDir, 'config.yaml');
+
+  // Idempotent + self-healing. The presence of `config.yaml` — NOT the `.forge/`
+  // directory alone — is what marks the home as initialized. Keying the
+  // no-clobber check on the config FILE means a half-init (dir created but config
+  // never written: disk full, permission error, or the process killed between
+  // mkdir and write) is COMPLETED on the next call instead of being permanently
+  // stuck behind a dir-exists early-return. We only ever ADD a missing
+  // config.yaml and never overwrite an existing one, so a real inited repo is
+  // still never clobbered. `mkdirSync({recursive})` is a no-op if the dir exists.
+  if (fsImpl.existsSync(configPath)) {
+    return { created: false, reason: 'config-exists', configPath };
+  }
+
+  fsImpl.mkdirSync(forgeDir, { recursive: true });
+  fsImpl.writeFileSync(configPath, renderMinimalConfig(deps), 'utf8');
+  return { created: true, configPath };
+}
+
+module.exports = {
+  ensureForgeHome,
+  isMutatingVerb,
+  renderMinimalConfig,
+  MUTATING_VERBS,
+};

package/lib/adapters/beads-kernel-compat.js

@@ -95,11 +95,60 @@ function readBeadsSidecar(beadsDir, file) {
   return found ? parseJsonl(fs.readFileSync(found, 'utf8'), path.basename(found)) : [];
 }
 
+// The *.jsonl sidecars this migrator knows how to map into the Kernel. Any other *.jsonl
+// present in the store is unmapped data; the loader records it so the import can report it
+// as an honest gap rather than dropping it silently.
+const HANDLED_SIDECARS = new Set([
+  'issues.jsonl',
+  'comments.jsonl',
+  'dependencies.jsonl',
+  'events.jsonl',
+  'interactions.jsonl',
+  'labels.jsonl',
+]);
+
+// Scan the same locations readBeadsSidecar reads (the dir itself, a `backup/` subdir, and the
+// parent) for *.jsonl files this migrator does NOT map. Returns their sorted, de-duplicated
+// basenames (`unmigrated`) so importBeadsSnapshot can surface each as a `sidecar.<name>`
+// field-gap — closing the "an unknown/config sidecar was dropped without a word" data-loss
+// class — plus any `scanErrors`: a candidate dir ABSENT from disk (ENOENT) is expected and
+// swallowed, but a REAL scan failure (EACCES/ENOTDIR/…) could hide sidecars silently, so it is
+// reported too rather than masquerading as "no sidecars".
+function detectUnmigratedSidecars(beadsDir) {
+  const dirs = [beadsDir, path.join(beadsDir, 'backup'), path.dirname(beadsDir)];
+  const unmigrated = new Set();
+  const scanErrors = [];
+  for (const dir of dirs) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir);
+    } catch (err) {
+      // A missing candidate dir is the normal case (not every layout has a backup/ subdir);
+      // only ENOENT is safe to swallow. Any other error is a real scan failure that may hide
+      // sidecars — record it so importBeadsSnapshot can surface an honest gap.
+      if (err && err.code !== 'ENOENT') {
+        scanErrors.push({ dir, code: err.code || 'EUNKNOWN' });
+      }
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.endsWith('.jsonl') && !HANDLED_SIDECARS.has(entry)) {
+        unmigrated.add(entry);
+      }
+    }
+  }
+  return {
+    unmigrated: [...unmigrated].sort((a, b) => a.localeCompare(b)),
+    scanErrors,
+  };
+}
+
 function loadBeadsSnapshotFromDirectory(beadsDir) {
   if (!beadsDir || typeof beadsDir !== 'string') {
     throw new TypeError('beadsDir must be a directory path');
   }
 
+  const { unmigrated, scanErrors } = detectUnmigratedSidecars(beadsDir);
   return {
     beadsDir,
     issues: readBeadsSidecar(beadsDir, 'issues.jsonl'),
@@ -108,6 +157,8 @@ function loadBeadsSnapshotFromDirectory(beadsDir) {
     events: readBeadsSidecar(beadsDir, 'events.jsonl'),
     interactions: readBeadsSidecar(beadsDir, 'interactions.jsonl'),
     labels: readBeadsSidecar(beadsDir, 'labels.jsonl'),
+    unmigratedSidecars: unmigrated,
+    sidecarScanErrors: scanErrors,
   };
 }
 
@@ -725,6 +776,22 @@ function importBeadsSnapshot(snapshot = {}, options = {}) {
     ...(Array.isArray(snapshot.events) ? snapshot.events : []).map(event => mapBeadsActivityEventToKernel(event, importedAt)),
     ...(Array.isArray(snapshot.interactions) ? snapshot.interactions : []).map(interaction => mapBeadsInteractionToKernel(interaction, importedAt)),
   ];
+  // Honest field-gap report: any *.jsonl sidecar present in the store that this migrator does
+  // not map (e.g. config.jsonl, or a future/unknown sidecar) is surfaced here rather than
+  // silently dropped. The loader records these on `unmigratedSidecars`.
+  for (const sidecar of Array.isArray(snapshot.unmigratedSidecars) ? snapshot.unmigratedSidecars : []) {
+    addGap(gaps, seenGaps, `sidecar.${sidecar}`, 'present in the Beads store but has no Kernel target — not migrated');
+  }
+  // A directory the sidecar scan could not read (EACCES/ENOTDIR/…, but NOT a merely-absent dir)
+  // might hide sidecars; surface it so the loss is never silent.
+  for (const scanError of Array.isArray(snapshot.sidecarScanErrors) ? snapshot.sidecarScanErrors : []) {
+    addGap(
+      gaps,
+      seenGaps,
+      `sidecar-scan.${path.basename(scanError.dir)}`,
+      `could not scan ${scanError.dir} for unmapped sidecars (${scanError.code}) — any sidecars there were not migrated`,
+    );
+  }
   const kernel = {
     issues: sourceIssues.map(issue => mapBeadsIssueToKernel(issue, importedAt, gaps, seenGaps)),
     dependencies: collectDependencies(normalizedSnapshot)

package/lib/adoption-profiles.js

@@ -1,6 +1,6 @@
 const YAML = require('yaml');
 
-const ADOPTION_VERSION = '0.0.15';
+const ADOPTION_VERSION = '0.0.16';
 const RUNTIME_ANCESTRY = 'forge.runtimeGraph.currentCommandFlow@0.0.17';
 const WORKFLOW_PHASES = Object.freeze(['plan', 'dev', 'validate', 'ship']);
 const WORKFLOW_GATES = Object.freeze(['gate.plan-exit', 'gate.dev-exit', 'gate.validate-exit', 'gate.ship-entry']);
@@ -32,12 +32,18 @@ function harnessAdapter(targets) {
   };
 }
 
-function adoptionConfig({ gatesEnabled, issueEnabled, harnessTargets, protectedPaths, rails }) {
+function adoptionConfig({ gatesEnabled, issueEnabled, harnessTargets, protectedPaths, rails, disabledRails = [] }) {
+  // Disabled rails are written through the same `workflow.gates.<rail-id>.enabled`
+  // toggle surface `forge gate disable` uses, so the resolver + the installed hooks
+  // read one consistent signal. Only unlocked rails (e.g. rail.tdd_intent) may appear.
+  const railGateOverrides = Object.fromEntries(
+    disabledRails.map(railId => [railId, { enabled: false }]),
+  );
   return {
     ...(rails ? { rails } : {}),
     workflow: {
       phases: enabledEntries(WORKFLOW_PHASES),
-      gates: enabledEntries(WORKFLOW_GATES, gatesEnabled),
+      gates: { ...enabledEntries(WORKFLOW_GATES, gatesEnabled), ...railGateOverrides },
     },
     adapters: {
       issue: issueAdapter(issueEnabled),
@@ -54,7 +60,14 @@ const PROFILE_CONFIGS = Object.freeze({
       gatesEnabled: false,
       issueEnabled: false,
       harnessTargets: [],
-      protectedPaths: ['.forge/config.yaml'],
+      // Minimal = zero active enforcement, so there is nothing left to guard: with the
+      // gates disabled and the TDD rail off, the protected-path guard has no enforcement
+      // surface to protect. Leaving it empty keeps `init --minimal` fully inert instead of
+      // contradicting itself by still guarding config.yaml.
+      protectedPaths: [],
+      // Minimal = no active enforcement: the TDD pre-commit rail is off (it is a
+      // strong default, not a hard floor), so `init --minimal` installs inert hooks.
+      disabledRails: ['rail.tdd_intent'],
     }),
   },
   standard: {

package/lib/beads-detect.js

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

package/lib/beads-nudge.js

@@ -0,0 +1,91 @@
+'use strict';
+
+const { resolveIssueBackend } = require('./issue-backend');
+const { detectBeadsJsonlSource } = require('./beads-detect');
+
+// Unmigrated legacy-store nudge (kernel issue a5399f3d — upgrade-safety
+// 0.0.10 -> current).
+//
+// The 0.0.10 -> current upgrade flipped the DEFAULT issue backend to the Kernel,
+// but the legacy -> kernel migration fires ONLY from `forge setup`/`init`, never
+// lazily on the issue path. So a user who runs `bun update` then `forge list` /
+// `forge ready` reads an EMPTY kernel and their 0.0.10 issues APPEAR GONE — the
+// data is safe on disk, just invisible, with no hint. This helper closes that
+// footgun: when the resolved backend is the (default) Kernel, a read comes back
+// empty, AND a legacy jsonl store still exists, it prints a one-time guided hint.
+//
+// It lives in this NEUTRAL module (not lib/commands/_issue.js) on purpose: the
+// message text names the retired backend + its `.beads` store, and _issue.js is a
+// D20 release-readiness hot-path surface that must stay free of those tokens (the
+// bd-call-site audit + kernel-backed checks scan it). Keeping the strings here
+// lets the hot path call a token-free helper.
+//
+// Best-effort and non-blocking: it NEVER throws and never alters the read result.
+// Fires at most once per project root per process to avoid spam.
+const NUDGE_READS = new Set(['list', 'ready']);
+const warnedRoots = new Set();
+
+// A kernel read looks empty when its contract data carries no issues. Handles the
+// issue.list/issue.ready shape ({ issues, count }) plus a bare array / null, and
+// is deliberately conservative: anything it cannot confirm as empty is treated as
+// NON-empty so a user with real kernel issues is never nagged.
+function kernelReadLooksEmpty(result) {
+  if (!result || typeof result !== 'object' || result.ok !== true) {
+    return false;
+  }
+  const data = result.data;
+  if (data === null || data === undefined) {
+    return true;
+  }
+  if (Array.isArray(data)) {
+    return data.length === 0;
+  }
+  if (Array.isArray(data.issues)) {
+    return data.issues.length === 0;
+  }
+  if (Array.isArray(data.items)) {
+    return data.items.length === 0;
+  }
+  if (typeof data.count === 'number') {
+    return data.count === 0;
+  }
+  return false;
+}
+
+function maybeWarnUnmigratedBeads(subcommand, result, projectRoot, rawOpts = {}) {
+  try {
+    if (!NUDGE_READS.has(subcommand) || !projectRoot) {
+      return;
+    }
+    if (warnedRoots.has(projectRoot)) {
+      return;
+    }
+    const env = rawOpts.env || process.env;
+    // Resolve the EFFECTIVE backend (default kernel). An explicit opt-in to the
+    // retired backend means the user chose it deliberately — nothing to nudge.
+    const backend = resolveIssueBackend({ deps: rawOpts, env, projectRoot, warn: () => {} });
+    if (backend !== 'kernel' || !kernelReadLooksEmpty(result)) {
+      return;
+    }
+    if (!detectBeadsJsonlSource(projectRoot)) {
+      return;
+    }
+    warnedRoots.add(projectRoot);
+    console.error(
+      '\n[forge] Legacy issue data detected (.beads/*.jsonl) but the Kernel issue store is empty.\n'
+      + 'Forge now defaults to the Kernel backend (breaking change since 0.0.10). Your legacy\n'
+      + 'issues are safe on disk but will not appear until migrated. To migrate:\n'
+      + '  forge migrate --from beads   # import your legacy issues into the Kernel\n'
+      + '  forge setup                  # (re)wire hooks + provision the Kernel store\n'
+      + 'Prefer to stay on the legacy backend? Set `issueBackend: beads` in .forge/config.yaml '
+      + '(or FORGE_ISSUE_BACKEND=beads).\n',
+    );
+  } catch (_err) { // NOSONAR S2486 — line-scoped; must sit on the catch line
+    /* the nudge is a best-effort hint; it must never break a read */
+  }
+}
+
+module.exports = {
+  maybeWarnUnmigratedBeads,
+  kernelReadLooksEmpty,
+};