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

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

package/docs/reference/COMMANDS.md

@@ -59,6 +59,7 @@ forge orient [--budget N] [--json]
 forge recap <issue> [--budget N] [--json]
 forge recall [query] [--limit N] [--all] [--json]
 forge remember <note> [--tag <label>]... [--json]
+forge skill for "<situation>" [--json]
 ```
 
 - `forge plan` creates the implementation plan, kernel issue, and feature branch/worktree from a researched feature description; it prints the created issue id, branch name, and the suggested next command.
@@ -66,7 +67,8 @@ forge remember <note> [--tag <label>]... [--json]
 - `forge validate` runs the validation orchestration pipeline (conflict markers, type check, lint, security, tests) with no arguments — see also `bun run check` under Validation And Packaging.
 - `forge ship` creates the pull request from validated feature work (wraps `gh pr create`); `--dry-run` previews without creating a PR.
 - `forge status` is the one-glance orientation command: where you are, what to run next, and your active work; `--full` also shows blocked/stale/recently-completed issues.
-- `forge prime` emits the bounded session-entry orientation envelope agents read at the start of a session.
+- `forge prime` emits the bounded session-entry orientation envelope agents read at the start of a session; it now leads with a bounded (<=20-line) **live-state** block — current stage, claimed issue(s), ready-work count, enabled gates/rails, and one progressive-adoption nudge — collected best-effort (never blocks, honest fallbacks) before the deterministic orientation.
+- `forge skill for "<situation>"` is the deterministic intent-to-skill router: it reads the canonical skill catalog and prints the best-fit Forge skill(s) plus why, as the reasoning fallback for harnesses without a SessionStart hook that auto-injects the `using-forge` dispatch skill. `--json` emits the machine-readable routing result. The `forge skill` noun is structured so later waves can add `forge skill eval` / `forge skill scores`.
 - `forge orient` emits bounded project orientation from deterministic source files (broader than `prime`, still token-budgeted via `--budget`).
 - `forge recap <issue>` is the issue-scoped counterpart to `forge orient`/`forge prime` — it summarizes a single issue from the same deterministic file assembly instead of the whole project. Requires an issue id; running it with no id (or `--help`) prints usage only.
 - `forge recall` retrieves project-memory notes from the kernel-backed memory store; omit `query` to list recent notes.
@@ -105,12 +107,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

@@ -6,13 +6,48 @@ polling / rerun / escalation loop a human otherwise runs by hand after
 the pre-merge gate (the embedded documentation-and-handoff gate in `/ship` and `/review`).
 
 ```bash
-forge shepherd <pr-number>
+forge shepherd daemon                      # singleton reconcile daemon: owns ALL open PRs
+forge shepherd <pr-number>                 # one bounded pass over a single PR
 forge shepherd <pr-number> --auto-rebase   # opt-in, default OFF
 forge shepherd <pr-number> --pull          # read-only: WHY it is blocked + what to fix
 forge shepherd <pr-number> --pull --json   # same payload as machine-readable JSON
 forge shepherd <pr-number> --bundle --json # read-only: the COMPLETE PR-state bundle
+forge shepherd watch <pr-number>           # single-PR constant monitor loop
+forge shepherd events <pr-number> --since <seq>  # read new journal events back
 ```
 
+## Daemon vs bounded pass (two modes, one verb)
+
+There are two ways to run the shepherd, both under the single `forge shepherd`
+verb:
+
+- **`forge shepherd daemon` — the singleton reconcile daemon (W-S4b), the default
+  ownership model.** It acquires the machine-wide shepherd lease for this repo
+  (exiting immediately as a clean no-op if a live daemon already owns it),
+  heartbeats, and converges the *entire* PR world every ~60s: self-registering
+  hand-opened PRs, restarting killed watchers, reaping verified orphan watchers,
+  converging CI check state into kernel verdicts, and retiring merged/closed PRs.
+  It **self-retires** — releases the lease, kills its verified children, exits —
+  once no PRs remain open. Today it is started explicitly — in a harness
+  background shell at session start, or `forge shepherd daemon` — not run by hand
+  as a detached process; automatic per-command launch (W-S4c) is a planned
+  follow-up, not yet wired. Once running, an agent does not poll: the daemon owns
+  the convergence loop.
+- **`forge shepherd <pr>` — one bounded pass.** Reads one PR's state, takes at
+  most one Tier-A action, exits. The point-in-time surface for a single PR (see
+  *Bounded-pass model* below).
+- **`forge shepherd watch <pr>` / `watch --adopt`** — foreground streaming watch of
+  one PR, or (`--adopt`) adopt every currently-open PR into the watcher set.
+- **`forge shepherd events <pr> --since <seq>`** — the event deltas for a PR since a
+  cursor; **`forge shepherd <pr> --pull --json` / `--bundle`** read the kernel verdict
+  + rollup without taking any action.
+
+Session start: if the repo has open PRs, start `forge shepherd daemon` in the
+harness background shell so it is reaped with the session. No liveness check is
+needed first — the O_EXCL singleton lease makes a duplicate start a clean no-op.
+(A `forge prime` open-PR + daemon-liveness line is a planned follow-up — W-S5 —
+not yet wired.)
+
 ## `--pull`: the actionable blocker payload
 
 `--pull` is a **strictly read-only** signal-gather. It computes the decision
@@ -67,6 +102,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 |
@@ -102,6 +174,42 @@ seconds and cancel-in-progress. The shepherd itself never waits in-process.
 - **Auth taxonomy.** 401 (expiry) pauses and surfaces; 403 insufficient-scope is
   a hard-stop; 403 with `Retry-After` honors the delay and resumes next pass.
 
+## GitHub Actions backstop — auto-updated heads re-trigger CI (`FORGE_PR_TOKEN`)
+
+The `pr-monitor.yml` Actions workflow can auto-update an otherwise-clean-but-behind
+PR branch (merge base into the head). That push must **re-trigger CI on the new
+head**, or the head sits with no required checks running and can never merge.
+
+GitHub deliberately does **not** start new workflow runs for events created with
+the default `GITHUB_TOKEN` — a `pull_request: synchronize` it produces lands in an
+*approval-required* state instead of running. So an auto-update authored by
+`GITHUB_TOKEN` leaves a **CI-dead head**. (Official rule:
+<https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow>.)
+
+**Fix (maintainer action required):** create a repository secret named
+**`FORGE_PR_TOKEN`** holding a fine-grained **PAT** (or GitHub-App installation
+token). The PAT's OWN permissions — not the workflow's `permissions:` block, which
+only governs the built-in `GITHUB_TOKEN` — must cover every call the step makes:
+
+| Permission | Why |
+| --- | --- |
+| **Contents: write** | push the update-branch merge to the head |
+| **Pull requests: write** | `PUT /pulls/{n}/update-branch` (the update-branch API) |
+| **Checks: write** | create the `forge/auto-update` marker check run |
+| **Workflows** | only if the base branch may change `.github/workflows/**` (the merge would carry it) |
+
+The auto-update-branch step uses the token and falls back to `GITHUB_TOKEN` when
+the secret is absent:
+
+```yaml
+GH_TOKEN: ${{ secrets.FORGE_PR_TOKEN || github.token }}
+```
+
+With the secret set, auto-updated heads re-run CI automatically. Without it, the
+workflow behaves exactly as before (no regression) — it just cannot auto-run CI on
+the updated head. Forge only wires the code path and reads the secret; **creating
+the secret is the maintainer's responsibility** — Forge never fabricates a token.
+
 ## Per-harness behavior
 
 - **Claude Code / Codex:** invoke `forge shepherd <pr>` directly; an external
@@ -111,5 +219,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/adapters/greptile-review-adapter.js

@@ -86,7 +86,7 @@ function matchThreadsToCommitsWithGit(threads, projectRoot, opts = {}) {
   }
 
   const exec = opts._exec || ((cmd, args) => {
-    return execFileSync(cmd, args, { encoding: 'utf8' });
+    return execFileSync(cmd, args, { encoding: 'utf8', windowsHide: true });
   });
 
   let sinceCommit = opts.sinceCommit;

package/lib/adapters/pr-state-adapter.js

@@ -78,9 +78,12 @@ class PrStateAdapter {
     this.id = options.id || 'pr-state-adapter';
     this.kind = 'pr-state';
     this.name = options.name || this.id;
+    // windowsHide keeps the shepherd's per-poll gh/git calls from flashing a
+    // console window on Windows when the watcher runs detached (issue 931e7924).
     const defaultRunner = (cmd, args, opts = {}) => execFileSync(cmd, args, {
       encoding: 'utf8',
       timeout: options.timeout || 30000,
+      windowsHide: true,
       ...(opts.cwd ? { cwd: opts.cwd } : {}),
     });
     this._gh = options.gh || defaultRunner;
@@ -127,17 +130,59 @@ class PrStateAdapter {
   }
 
   /**
-   * Read the branch-protection required-checks set.
+   * Read the required-checks set for a PR, with a two-source strategy so the
+   * verdict is not permanently UNKNOWN in CI.
    *
-   * Returns `null` when the protection endpoint is unreadable (e.g. 403
-   * insufficient scope, the branch is not protected, or the payload shape is
-   * unexpected) so the caller can escalate rather than guess. Re-throws non-auth
-   * errors.
+   * 1. **Branch protection** (`.../protection/required_status_checks`) — the
+   *    authoritative set, but this REST endpoint needs repo `Administration:read`,
+   *    which GitHub Actions' `GITHUB_TOKEN` can NEVER hold (administration is not a
+   *    grantable `permissions:` scope). So in CI this ALWAYS 403/404s and the set
+   *    was permanently null → verdict UNKNOWN on every PR.
+   * 2. **statusCheckRollup `isRequired`** (GraphQL, on the PR head commit) — the
+   *    fallback. It is readable with the plain PR-read scope the Actions token DOES
+   *    hold (it is what `gh pr checks --required` uses) and it covers BOTH classic
+   *    branch protection AND repository rulesets.
    *
-   * @param {{ owner: string, repo: string, base: string }} ctx
+   * Known limitation of the fallback: the rollup only lists contexts that
+   * PRODUCED a run, so a required context that never ran at all is invisible on
+   * this path — missing-required detection is best-effort when the source is the
+   * rollup. That is strictly better than a permanent UNKNOWN.
+   *
+   * Returns `null` only when BOTH sources are unreadable (existing fail-closed
+   * behaviour). `lastRequiredSource` records which source answered
+   * (`'protection'` | `'rollup'` | `null`) so callers can surface it as evidence.
+   * Re-throws non-auth protection errors (unchanged).
+   *
+   * @param {{ owner: string, repo: string, base: string, pr?: string|number }} ctx
    * @returns {Promise<string[] | null>}
    */
-  async readRequiredChecks({ owner, repo, base }) {
+  async readRequiredChecks({ owner, repo, base, pr }) {
+    this.lastRequiredSource = null;
+    const fromProtection = this._readProtectionRequired({ owner, repo, base });
+    if (Array.isArray(fromProtection)) {
+      this.lastRequiredSource = 'protection';
+      return fromProtection;
+    }
+    // Protection unreadable (auth/scope/not-protected/unexpected shape) — fall back
+    // to the rollup `isRequired` set the Actions token CAN read.
+    const fromRollup = this._readRollupRequired({ owner, repo, pr });
+    if (Array.isArray(fromRollup)) {
+      this.lastRequiredSource = 'rollup';
+      return fromRollup;
+    }
+    return null;
+  }
+
+  /**
+   * Branch-protection required set, or `null` when unreadable (auth/scope/
+   * not-protected/unexpected shape). Re-throws non-auth errors so a genuine
+   * outage is not silently masked. Split out so `readRequiredChecks` can fall
+   * back cleanly.
+   *
+   * @param {{ owner: string, repo: string, base: string }} ctx
+   * @returns {string[] | null}
+   */
+  _readProtectionRequired({ owner, repo, base }) {
     const apiPath = `repos/${owner}/${repo}/branches/${encodeURIComponent(base)}/protection/required_status_checks`;
     try {
       const raw = this._gh('gh', ['api', apiPath]);
@@ -150,13 +195,63 @@ class PrStateAdapter {
     } catch (error) {
       const auth = classifyAuthError(error);
       if (auth) {
-        // Unreadable protection (auth/scope/not-protected) — caller escalates.
+        // Unreadable protection (auth/scope/not-protected) — fall back to rollup.
         return null;
       }
       throw error;
     }
   }
 
+  /**
+   * Fallback required set from the PR head commit's `statusCheckRollup`, reading
+   * per-context `isRequired(pullRequestNumber:)` via GraphQL. Readable with plain
+   * PR-read scope (unlike branch protection). Returns the deduped names of every
+   * required CheckRun/StatusContext, `[]` when the rollup is readable but nothing
+   * is required, or `null` when the rollup itself is unreadable (fail-closed).
+   *
+   * @param {{ owner: string, repo: string, pr?: string|number }} ctx
+   * @returns {string[] | null}
+   */
+  _readRollupRequired({ owner, repo, pr }) {
+    const prNum = Number.parseInt(String(pr), 10);
+    if (!Number.isInteger(prNum) || prNum <= 0) return null;
+    // pr is inlined as a validated integer (no injection); owner/repo are GitHub
+    // name-charset identifiers. Shape verified against the live GraphQL API.
+    const query = `query { repository(owner: "${owner}", name: "${repo}") { `
+      + `pullRequest(number: ${prNum}) { headRef { target { ... on Commit { `
+      + `statusCheckRollup { contexts(first: 100) { nodes { __typename `
+      + `... on CheckRun { name isRequired(pullRequestNumber: ${prNum}) } `
+      + `... on StatusContext { context isRequired(pullRequestNumber: ${prNum}) } `
+      + `} } } } } } } } }`;
+    try {
+      const raw = this._gh('gh', ['api', 'graphql', '-f', `query=${query}`]);
+      const data = JSON.parse(raw || '{}');
+      const nodes = data
+        && data.data
+        && data.data.repository
+        && data.data.repository.pullRequest
+        && data.data.repository.pullRequest.headRef
+        && data.data.repository.pullRequest.headRef.target
+        && data.data.repository.pullRequest.headRef.target.statusCheckRollup
+        && data.data.repository.pullRequest.headRef.target.statusCheckRollup.contexts
+        && data.data.repository.pullRequest.headRef.target.statusCheckRollup.contexts.nodes;
+      // No rollup at all (e.g. statusCheckRollup null) → cannot determine the set.
+      if (!Array.isArray(nodes)) return null;
+      const required = [];
+      for (const node of nodes) {
+        if (node && node.isRequired === true) {
+          const name = node.name || node.context;
+          if (name) required.push(name);
+        }
+      }
+      // Dedupe matrix duplicates (same context reported by multiple jobs).
+      return [...new Set(required)];
+    } catch {
+      // GraphQL unreadable (auth/network/etc.) — fail closed to null.
+      return null;
+    }
+  }
+
   /**
    * Read ahead/behind divergence against the base ref.
    *

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/agents-config.js

@@ -93,6 +93,10 @@ Forge currently supports Claude Code, Codex, and Cursor. Hermes support is plann
 - **Codex** - OpenAI's CLI agent, skills-based workflow
 - **Cursor** - IDE-integrated, native Plan/Ask/Debug modes
 
+## Skill Dispatch (auto-trigger)
+
+Before ANY response — including clarifying questions or exploring the codebase — if there is even a 1% chance a Forge skill applies, invoke it, then announce \`Using [skill] to [purpose]\`. Invoke the \`using-forge\` dispatch skill (auto-discovered from your agent's own skills — Forge setup installs it into each harness's skills dir; it carries the 1%-rule and routing table), or run \`forge skill for "<situation>"\` for the deterministic best-fit skill. This is agent-agnostic — never branch on harness identity.
+
 ## Quick Start
 
 \`\`\`bash
@@ -962,6 +966,7 @@ Choose based on server documentation.
 module.exports = {
   detectProjectMetadata,
   generateAgentsMd,
+  generateAgentsMdContent,
   generateCursorConfig,
   generateArchitectureDoc,
   generateConfigurationDoc,