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

package/AGENTS.md

@@ -17,7 +17,7 @@ This project ships a **default TDD-first workflow template** with 6 workflow sta
 
 **Utility**: `/status` — Context check before starting work (not a numbered stage)
 
-**Utility**: `/shepherd <pr>` — Monitor-driven PR shepherd: one bounded pass that reads CI and check state, re-runs a flaky required check (Tier-A), or escalates, then hands off. It is a utility command, **not** a workflow stage, and does not sit between `/review` and the handoff. It **never merges** (the human merges in the GitHub UI) and **never resolves review threads** (that stays with `/review`). `--auto-rebase` is opt-in and default OFF. See [docs/reference/shepherd.md](docs/reference/shepherd.md).
+**Utility**: `/shepherd <pr>` — Autonomous PR ownership. `forge shepherd daemon` is a singleton reconcile daemon that owns **all** open PRs for the repo: it converges CI check state into kernel verdicts, re-runs flaky required checks (Tier-A), reaps orphan watchers, and self-retires when no PRs remain — so agents read verdicts (`forge shepherd <pr> --pull --json`, `forge shepherd events`) instead of hand-polling. `forge shepherd <pr>` is the one-shot bounded pass for a single PR. It is a utility, **not** a workflow stage. It **never merges** (the human merges in the GitHub UI) and **never resolves review threads** (that stays with `/review`). `--auto-rebase` is opt-in and default OFF; kill-switches: `FORGE_SHEPHERD_DISABLE`, `forge gate disable rail.auto_shepherd`. **Startup/containment**: the daemon is a repo singleton (O_EXCL lease — a duplicate start is a clean no-op) started in the harness background shell so it is session-reaped; agents never launch it as a detached spawn (automatic per-command launch is a planned follow-up, W-S4c). See [docs/reference/shepherd.md](docs/reference/shepherd.md).
 
 ## Automatic Change Classification
 

package/bin/forge-cmd.js

@@ -72,7 +72,7 @@ function findPlanDocForBranch(branch) {
 
 const COMMAND_DESCRIPTIONS = {
 	status: 'Detect current workflow stage (1-7)',
-	plan: 'Create branch + Beads + design doc',
+	plan: 'Create branch + issue + design doc',
 	dev: 'Implement with TDD (RED-GREEN-REFACTOR)',
 	validate: 'Run type check, lint, security, tests',
 	check: 'Alias for validate (deprecated — use validate)',

package/bin/forge.js

@@ -4159,6 +4159,11 @@ async function main() {
       console.error(`Error running '${command}':`, err.message);
       process.exit(1);
     }
+    // NOTE: the autonomous-shepherd per-command trigger is intentionally NOT wired here.
+    // The reconcile engine + daemon land in this PR; the auto-fire wiring is deferred to a
+    // follow-up (W-S4c) because a naive dispatch-finally trigger spawns a session-outliving
+    // daemon on EVERY command, which breaks test isolation (Windows rmSync EBUSY) and needs
+    // its own firing-policy + containment design. Start the daemon via `forge shepherd daemon`.
     return;
   }
 

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.

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
@@ -139,6 +174,42 @@ same verb (or `forge shepherd events`) on its own cadence.
 - **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

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/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,

package/lib/commands/_issue.js

@@ -2,7 +2,6 @@
 
 const { runIssueOperation: defaultRunIssueOperation } = require('../forge-issues');
 const { resolveIssueBackend, hasExplicitBackendSignal, shouldUseKernelBroker } = require('../issue-backend');
-const { maybeWarnUnmigratedBeads } = require('../beads-nudge');
 const {
   ISSUE_COMMAND_SCHEMA_VERSION,
   ISSUE_COMMAND_ERROR_SCHEMA_VERSION,
@@ -17,11 +16,10 @@ const { checkReadFirst } = require('../grounding/read-first');
 const { recordContextLoaded } = require('../grounding/context-events');
 
 // The Forge issue command surface. Each subcommand routes through the shared
-// runIssueOperation, which selects the active backend (Kernel by --kernel /
-// --issue-backend kernel / FORGE_ISSUE_BACKEND=kernel; Beads otherwise) and performs
-// any backend-specific argument translation. This module therefore carries NO direct
-// issue-tracker invocation or argv translation — those live in the backend
-// abstraction (lib/forge-issues.js + the issue adapters).
+// runIssueOperation, which dispatches to the Forge Kernel — the only issue backend.
+// This module therefore carries NO direct issue-tracker invocation or argv
+// translation — those live in the backend abstraction (lib/forge-issues.js + the
+// kernel issue adapter).
 const SUBCOMMANDS = {
   create: {
     description: 'Create an issue via Forge',
@@ -67,10 +65,8 @@ const SUBCOMMANDS = {
     description: 'Show issue statistics via Forge',
     usage: 'forge issue stats [flags]',
   },
-  // KAP-7: derived read queries. The backend abstraction maps each to its tracker
-  // equivalent (the Kernel passes the operation name through unchanged; the Beads
-  // backend maps each to its passthrough subcommand). They are READS, so they are
-  // intentionally NOT in WRITE_SUBCOMMANDS.
+  // KAP-7: derived read queries. The Kernel passes the operation name through
+  // unchanged. They are READS, so they are intentionally NOT in WRITE_SUBCOMMANDS.
   blocked: {
     description: 'Show blocked issues via Forge',
     usage: 'forge issue blocked [flags]',
@@ -106,9 +102,7 @@ const SUBCOMMANDS = {
     usage: 'forge issue owns <id> [--json]',
   },
   // Active-lease listing (kernel issue 7dc229d4). A bare passthrough to the Kernel
-  // lease table (kernel_claims); Beads has no lease table to enumerate, so
-  // forge-issues.js rejects the Beads path explicitly. A READ, so intentionally NOT
-  // in WRITE_SUBCOMMANDS.
+  // lease table (kernel_claims). A READ, so intentionally NOT in WRITE_SUBCOMMANDS.
   claims: {
     description: 'Show active issue leases (claims) via Forge',
     usage: 'forge issue claims [--json]',
@@ -389,8 +383,7 @@ function formatIssueHelp() {
 }
 
 // Map a CLI subcommand to the backend operation name. `dep` fans out to
-// `dep.<action>`; every other subcommand uses its own name (the backend performs
-// any tracker-specific translation, e.g. Beads claim -> `update <id> --claim`).
+// `dep.<action>`; every other subcommand uses its own name.
 function resolveIssueOperation(subcommand, args) {
   if (subcommand === 'dep') {
     return `dep.${normalizeArgs(args)[0]}`;
@@ -400,10 +393,8 @@ function resolveIssueOperation(subcommand, args) {
 
 // The Kernel create payload (buildCreatePayload) reads only the --title flag, so a
 // bare leading positional (`forge create "title"`) would be ignored and the title
-// would default to the minted UUID. For parity on the KERNEL PATH ONLY, translate a
-// single leading bare positional into `--title <value>` when no explicit
-// --title/--title= is present. The Beads backend keeps its native positional
-// handling (this never runs for the Beads path).
+// would default to the minted UUID. Translate a single leading bare positional into
+// `--title <value>` when no explicit --title/--title= is present.
 function withKernelCreateTitle(args) {
   const hasTitle = args.some(
     arg => arg === '--title' || (typeof arg === 'string' && arg.startsWith('--title=')),
@@ -454,10 +445,12 @@ function validateDepArgs(args) {
   return null;
 }
 
-// Resolve the active issue backend (kernel|beads) and thread it into opts so the
-// shared runIssueOperation deps see it. OPT-IN ONLY: opts is left byte-identical
-// when no explicit signal is present (env/config/explicit), preserving the Beads
-// default path. A copy is returned — the caller's opts object is never mutated.
+// Normalize any explicit issue-backend signal and thread the resolved value into
+// opts so the shared runIssueOperation deps see it. OPT-IN ONLY: opts is left
+// byte-identical when no explicit signal is present (env/config/explicit), so the
+// no-signal path stays untouched. A copy is returned — the caller's opts object is
+// never mutated. A retired value (`beads`) warns here with the migrate pointer and
+// resolves to the kernel.
 function withResolvedIssueBackend(projectRoot, opts = {}) {
   const env = opts.env || process.env;
   const signalContext = { deps: opts, env, projectRoot };
@@ -479,13 +472,13 @@ function withResolvedIssueBackend(projectRoot, opts = {}) {
 
 // The Kernel broker returns the issue-command contract shape
 // ({ ok, schema_version, command, data, next_commands } or { ok:false, error })
-// rather than the Beads-style { success, output }. The bin/forge.js result printer
+// rather than the legacy { success, output }. The bin/forge.js result printer
 // keys on `success`/`output`, so a raw kernel contract would render as
 // "Command failed". Normalize ONLY the contract shape (ok defined, success
 // undefined) into { success, output } here, at the command boundary — the kernel
 // contract itself stays untouched. Every other result passes through byte-identical.
 //
-// Response-contract parity (the Beads behavior the Kernel replaced):
+// Response-contract guarantees:
 //   * SUCCESS  → the printed envelope carries `ok:true` (consumers gate on it).
 //   * FAILURE  → the contract `exit_code` is surfaced as `result.exitCode` so the bin
 //                printer exits with the error class's code (not always 1); and on
@@ -609,8 +602,7 @@ function splitLeadingIds(args = []) {
 // which broke envelope parity for multi-id close. `ok` is true only when every id
 // closed; per-id outcomes live in `data.results` and the contract `exit_code` of the
 // first failure is surfaced as `exitCode` so the bin printer exits with the error
-// class's code. KERNEL PATH ONLY: the Beads passthrough keeps its single
-// `close id1 id2 ...` invocation.
+// class's code.
 async function runKernelBatchClose(runner, operation, ids, flags, projectRoot, opts, verifyEnabled = false) {
   const results = [];
   let allSucceeded = true;
@@ -700,13 +692,11 @@ async function runIssueSubcommand(subcommand, args, projectRoot, rawOpts = {}) {
     return { success: false, error: `Unknown issue subcommand '${subcommand}'.\n\n${formatIssueHelp()}` };
   }
 
-  // Backend-agnostic --help short-circuit: print the subcommand's usage and return
-  // BEFORE resolving the backend or dispatching any operation. Without this, a help
-  // request was forwarded to the active backend as an operation arg — absorbed
-  // harmlessly by Beads (which swallowed --help), but broken under the Kernel default:
-  // the plural path failed with a bare "Command failed" and the singular path
-  // SILENTLY minted a junk issue (and could queue a GitHub projection). Help must
-  // never touch a backend.
+  // --help short-circuit: print the subcommand's usage and return BEFORE resolving
+  // the backend or dispatching any operation. Without this, a help request is
+  // forwarded to the Kernel as an operation arg: the plural path fails with a bare
+  // "Command failed" and the singular path SILENTLY mints a junk issue (and could
+  // queue a GitHub projection). Help must never touch a backend.
   if (normalizeArgs(args).some(arg => arg === '--help' || arg === '-h')) {
     return { success: true, output: `${spec.usage}\n\n${spec.description}` };
   }
@@ -749,17 +739,16 @@ async function runIssueSubcommand(subcommand, args, projectRoot, rawOpts = {}) {
     }
   }
 
-  // Both backends are reached through the same runIssueOperation seam. Naming the
-  // injected local `runIssueOperation` keeps the dispatch a literal call to a binding
-  // named `runIssueOperation` (the kernel-evidence gate is syntactic) while still
-  // honoring an injected runner; the `kernelBroker: opts.kernelBroker` passthrough is
-  // a runtime no-op (undefined under Beads) that documents the Kernel-capable surface.
+  // The Kernel is reached through the runIssueOperation seam. Naming the injected
+  // local `runIssueOperation` keeps the dispatch a literal call to a binding named
+  // `runIssueOperation` (the kernel-evidence gate is syntactic) while still honoring
+  // an injected runner.
   const runIssueOperation = opts.runIssueOperation || defaultRunIssueOperation;
   const operation = resolveIssueOperation(subcommand, args);
   const operationArgs = resolveOperationArgs(subcommand, args, opts);
 
-  // Check-after-write (gate.issue_verify): resolved ONCE per invocation, kernel
-  // path only. Reads and the Beads path never trigger a read-back.
+  // Check-after-write (gate.issue_verify): resolved ONCE per invocation. Reads never
+  // trigger a read-back.
   const verifyEnabled = VERIFIED_SUBCOMMANDS.has(subcommand)
     && shouldUseKernelBroker(opts)
     && isIssueVerifyEnabled(projectRoot, opts);
@@ -779,7 +768,7 @@ async function runIssueSubcommand(subcommand, args, projectRoot, rawOpts = {}) {
     projectRoot,
     { ...opts, kernelBroker: opts.kernelBroker },
   );
-  // Verify only a SUCCESSFUL kernel-contract mutation (ok:true, not a Beads
+  // Verify only a SUCCESSFUL kernel-contract mutation (ok:true, not a legacy
   // {success,output} shape). Warn-only: attaches verified/mismatches, never
   // changes the result's success or exit code.
   if (verifyEnabled && result && typeof result === 'object' && result.ok === true && result.success === undefined) {
@@ -787,10 +776,6 @@ async function runIssueSubcommand(subcommand, args, projectRoot, rawOpts = {}) {
   }
   // Best-effort, non-blocking: mirror a stage-transition comment into stage_runs.
   recordStageTransitionFromComment(subcommand, operationArgs, result, opts);
-  // Best-effort, non-blocking: nudge a returning 0.0.10 user whose empty Kernel
-  // read hides an unmigrated legacy issue store (kernel issue a5399f3d). The hint
-  // text lives in lib/beads-nudge.js so this hot path stays token-free.
-  maybeWarnUnmigratedBeads(subcommand, result, projectRoot, rawOpts);
   // Grounding (gate.read_first): a successful `forge show <id>` counts as reading
   // the issue, so append a `context.loaded` event. Best-effort and awaited (a
   // fire-and-forget append could lose the event when the CLI process exits); a

package/lib/commands/_manifest.js

@@ -26,7 +26,6 @@ const commands = [
   { file: "add.js", module: require("./add") },
   { file: "audit.js", module: require("./audit") },
   { file: "blocked.js", module: require("./blocked") },
-  { file: "board.js", module: require("./board") },
   { file: "claim.js", module: require("./claim") },
   { file: "claims.js", module: require("./claims") },
   { file: "clean.js", module: require("./clean") },
@@ -73,6 +72,7 @@ const commands = [
   { file: "shepherd.js", module: require("./shepherd") },
   { file: "ship.js", module: require("./ship") },
   { file: "show.js", module: require("./show") },
+  { file: "skill.js", module: require("./skill") },
   { file: "stage.js", module: require("./stage") },
   { file: "stale.js", module: require("./stale") },
   { file: "status.js", module: require("./status") },