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

package/skills/portability/evals/evals.json

@@ -0,0 +1,34 @@
+[
+  {
+    "query": "Back up the kernel backlog to a git-tracked JSONL snapshot.",
+    "should_trigger": true
+  },
+  {
+    "query": "Export the kernel backlog to git-tracked JSONL.",
+    "should_trigger": true
+  },
+  {
+    "query": "Migrate our Beads issue store into the Forge kernel.",
+    "should_trigger": true
+  },
+  {
+    "query": "Dry-run the beads migration and show what would be imported.",
+    "should_trigger": true
+  },
+  {
+    "query": "Re-import the exported backlog JSONL into the kernel.",
+    "should_trigger": true
+  },
+  {
+    "query": "Migrate the database schema to add the new billing column.",
+    "should_trigger": false
+  },
+  {
+    "query": "Sync my feature branch with main before opening the PR.",
+    "should_trigger": false
+  },
+  {
+    "query": "Remember this decision for later.",
+    "should_trigger": false
+  }
+]

package/skills/portability/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "portability",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 957,
+      "body_lines": 31,
+      "score": 50
+    },
+    "caps": {
+      "desc_within": true,
+      "body_within": true,
+      "score": 100
+    },
+    "description_quality": {
+      "has_trigger_cues": true,
+      "has_disambiguation_cues": true,
+      "adequate_length": true,
+      "score": 100
+    }
+  },
+  "router_reachability": {
+    "has_curated_rule": true,
+    "router_exempt": false,
+    "fixtures": "present",
+    "fixtures_total": 5,
+    "fixtures_best_hit": 5,
+    "reachable": true,
+    "keyword_alignment": 1
+  },
+  "behavioral": {
+    "trigger_recall": null,
+    "trigger_precision": null,
+    "disambiguation": null,
+    "chain_correctness": null,
+    "outcome_quality": null,
+    "variance": null,
+    "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
+  },
+  "composite": 85
+}

package/skills/research/SKILL.md

@@ -14,6 +14,7 @@ description: >
   heavyweight EXTERNAL market/competitive report (paid Parallel AI); `plan` for the full plan
   stage (brainstorm + tasks); `dev` or `validate` to implement or scan rather than investigate.
 allowed-tools: Bash, Read, Write, Grep, Glob, WebSearch, WebFetch
+terminal: true
 ---
 
 Investigate anything, from anywhere: verify a claim, search the web, find better options, pull

package/skills/research/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "research",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 1014,
+      "body_lines": 179,
+      "score": 33
+    },
+    "caps": {
+      "desc_within": true,
+      "body_within": true,
+      "score": 100
+    },
+    "description_quality": {
+      "has_trigger_cues": false,
+      "has_disambiguation_cues": true,
+      "adequate_length": true,
+      "score": 60
+    }
+  },
+  "router_reachability": {
+    "has_curated_rule": true,
+    "router_exempt": false,
+    "fixtures": "present",
+    "fixtures_total": 5,
+    "fixtures_best_hit": 2,
+    "reachable": true,
+    "keyword_alignment": 0.4
+  },
+  "behavioral": {
+    "trigger_recall": null,
+    "trigger_precision": null,
+    "disambiguation": null,
+    "chain_correctness": null,
+    "outcome_quality": null,
+    "variance": null,
+    "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
+  },
+  "composite": 60
+}

package/skills/review/SKILL.md

@@ -13,12 +13,18 @@ description: >
   closing issues), ship (pushes the branch + opens the PR), validate (PRE-PR local
   type/lint/test/security), and sonarcloud / sonarcloud-analysis (only QUERY SonarCloud data).
 allowed-tools: Bash, Read, Edit, Grep, Glob
+next: verify
+terminal: false
+handoffs:
+  - shepherd
 ---
 
 Process ALL pull request issues including GitHub Actions failures, review-agent inline comments (Greptile, CodeRabbit, Qodo, or human reviewers), SonarCloud analysis, and other CI/CD checks.
 
 # Review
 
+> **Chain (HARD-GATE):** the successor depends on the change classification (source of truth: lib/workflow/stages.js) — Critical → `verify` (post-merge health check); Standard ENDS at `review`. `verify` is the default/critical-path next. While the PR is still open you may hand off to `shepherd` to watch checks toward merge. `review` never merges.
+
 This skill handles ALL issues that arise after creating a pull request.
 
 ## Usage

package/skills/review/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "review",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 988,
+      "body_lines": 476,
+      "score": 4
+    },
+    "caps": {
+      "desc_within": true,
+      "body_within": true,
+      "score": 100
+    },
+    "description_quality": {
+      "has_trigger_cues": true,
+      "has_disambiguation_cues": true,
+      "adequate_length": true,
+      "score": 100
+    }
+  },
+  "router_reachability": {
+    "has_curated_rule": true,
+    "router_exempt": false,
+    "fixtures": "present",
+    "fixtures_total": 5,
+    "fixtures_best_hit": 3,
+    "reachable": true,
+    "keyword_alignment": 0.6
+  },
+  "behavioral": {
+    "trigger_recall": null,
+    "trigger_precision": null,
+    "disambiguation": null,
+    "chain_correctness": null,
+    "outcome_quality": null,
+    "variance": null,
+    "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
+  },
+  "composite": 71
+}

package/skills/rollback/SKILL.md

@@ -13,6 +13,7 @@ description: >
   (shepherd), the post-merge CI health check on master (verify), pushing a branch or opening a
   PR (ship), or ordinary issue status/field edits (issue-basics).
 allowed-tools: Bash, Read, Edit, Grep, Glob
+terminal: true
 ---
 
 Comprehensive rollback system with multiple methods and automatic USER content preservation.

package/skills/rollback/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "rollback",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 965,
+      "body_lines": 95,
+      "score": 43
+    },
+    "caps": {
+      "desc_within": true,
+      "body_within": true,
+      "score": 100
+    },
+    "description_quality": {
+      "has_trigger_cues": true,
+      "has_disambiguation_cues": true,
+      "adequate_length": true,
+      "score": 100
+    }
+  },
+  "router_reachability": {
+    "has_curated_rule": true,
+    "router_exempt": false,
+    "fixtures": "present",
+    "fixtures_total": 6,
+    "fixtures_best_hit": 1,
+    "reachable": true,
+    "keyword_alignment": 0.17
+  },
+  "behavioral": {
+    "trigger_recall": null,
+    "trigger_precision": null,
+    "disambiguation": null,
+    "chain_correctness": null,
+    "outcome_quality": null,
+    "variance": null,
+    "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
+  },
+  "composite": 83
+}

package/skills/setup/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: setup
+description: >
+  Forge install & setup lifecycle. `forge setup` interactively configures Forge for your
+  coding agents; `forge init [--profile minimal|standard|full]` writes the
+  adoption config in a fresh repo; `forge doctor` reports whether the kernel DB is on a
+  cloud/network path; `forge upgrade [--dry-run]` previews + self-heals upgrade readiness;
+  `forge hooks install --global` installs native hooks; `forge reset --soft|--hard --force`
+  and `forge reinstall --force` undo/redo the install; `forge recommend` lists suggested
+  tools. Use when the user says "install/set up forge", "init forge", "adoption profile",
+  "forge doctor", "upgrade forge", "install the hooks globally", or "reset/reinstall forge".
+  Footguns: setup is interactive — pass `--yes` in automation; `doctor` only checks the
+  kernel-DB filesystem class, NOT general health; `upgrade` self-heals Forge state, NOT the
+  npm package; reset/reinstall need `--force`. NOT toggling a gate/rail (gates), NOT
+  orienting in a set-up repo (status), NOT installing project deps (dev).
+allowed-tools: Bash, Read, Grep, Glob
+terminal: true
+---
+
+Getting Forge installed, configured, upgraded, and diagnosed in a repo. These are the bootstrap and maintenance commands — distinct from the everyday workflow stages.
+
+# Install & configure
+
+```bash
+forge setup                      # interactive agent configuration (Claude/Cursor/Codex …)
+forge setup --yes                # non-interactive: accept defaults (use this in automation)
+forge setup --agents claude,cursor --skip-external   # target specific harnesses, skip service prompts
+forge setup --path <dir> --dry-run                   # preview against another dir, write nothing
+```
+
+`forge setup` is **interactive by default**. In any automated/agent context pass `--yes` (or `--non-interactive`) so it never blocks on a prompt.
+
+# Initialize a fresh repo
+
+```bash
+forge init --minimal             # shortcut for --profile minimal --yes
+forge init --profile standard --harness claude,cursor
+forge init --classification standard --dry-run       # preview the adoption config
+```
+
+`forge init` writes the Forge adoption config (`.forge/config.yaml`). The profile picks how much enforcement ships on: `minimal` (rails off) → `standard` → `full`. This configures the workflow; toggling an individual gate afterward is the **gates** skill.
+
+# Diagnose
+
+```bash
+forge doctor            # is the kernel DB on a cloud-synced / network path? (reliability signal)
+forge doctor --json     # machine-readable
+```
+
+`forge doctor` is **narrow**: it reports the filesystem class of the Forge kernel database path (local / cloud-synced / network) so you can catch the reliability footgun of running the DB on OneDrive/Dropbox/a network share. It is **not** a general health check.
+
+# Upgrade readiness
+
+```bash
+forge upgrade --dry-run    # preview the planned self-heal, change nothing
+forge upgrade              # apply safe self-heal steps to make the repo upgrade-ready
+```
+
+`forge upgrade` previews and applies **safe self-heal** steps for Forge's own state. It does **not** update the installed npm package — use your package manager for that.
+
+# Global hooks
+
+```bash
+forge hooks install --global                       # install native hooks for all harnesses
+forge hooks install --global --harness codex       # scope to one harness (codex|hermes|all)
+forge hooks install --global --dry-run             # preview
+```
+
+`--global` is the required consent flag — it opts you into installing hooks at the user level. (The other `forge hooks` subcommands — `session-start`, `inbox-pickup`, `shepherd-events`, `memory-recall`, `capture` — are machine-facing hook emitters the harness calls, not things you run by hand.)
+
+# Undo / redo the install
+
+```bash
+forge reset --soft --force     # remove .forge/ config only (keeps commands, rules, agents)
+forge reset --hard --force     # remove ALL forge-managed files (keeps user-created files)
+forge reinstall --force        # remove + re-run default setup in one step
+```
+
+`reset` and `reinstall` are destructive, so `--force` is required. `reset` with no `--soft`/`--hard` just prints usage.
+
+# Recommend tooling
+
+```bash
+forge recommend         # suggest tools/integrations for the current project
+```
+
+## Boundaries
+
+- Toggling a single gate/rail (e.g. TDD, kernel-tracking) is **gates** — `init` *writes* the initial config; `gates` *flips* one afterward.
+- "Where am I / how is forge set up" in an already-configured repo is **status** / **kernel**, not setup.
+- Installing project dependencies (`bun install`) is **dev**, not `forge setup`.

package/skills/setup/evals/evals.json

@@ -0,0 +1,42 @@
+[
+  {
+    "query": "Install Forge into this repo and configure it for Claude and Cursor.",
+    "should_trigger": true
+  },
+  {
+    "query": "Initialize forge in this fresh repository with the minimal adoption profile.",
+    "should_trigger": true
+  },
+  {
+    "query": "Run forge doctor — is the kernel database on a cloud-synced path?",
+    "should_trigger": true
+  },
+  {
+    "query": "Upgrade forge and self-heal anything unsafe first.",
+    "should_trigger": true
+  },
+  {
+    "query": "Install the Forge native hooks globally for Codex.",
+    "should_trigger": true
+  },
+  {
+    "query": "Undo the forge install — reset this repo's forge files.",
+    "should_trigger": true
+  },
+  {
+    "query": "Disable the TDD gate, it's blocking my commit.",
+    "should_trigger": false
+  },
+  {
+    "query": "Set up the database schema for the new billing feature.",
+    "should_trigger": false
+  },
+  {
+    "query": "Upgrade the eslint dependency to the latest version.",
+    "should_trigger": false
+  },
+  {
+    "query": "Install the project dependencies with bun install.",
+    "should_trigger": false
+  }
+]

package/skills/setup/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "setup",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 1021,
+      "body_lines": 74,
+      "score": 43
+    },
+    "caps": {
+      "desc_within": true,
+      "body_within": true,
+      "score": 100
+    },
+    "description_quality": {
+      "has_trigger_cues": true,
+      "has_disambiguation_cues": true,
+      "adequate_length": true,
+      "score": 100
+    }
+  },
+  "router_reachability": {
+    "has_curated_rule": true,
+    "router_exempt": false,
+    "fixtures": "present",
+    "fixtures_total": 6,
+    "fixtures_best_hit": 6,
+    "reachable": true,
+    "keyword_alignment": 1
+  },
+  "behavioral": {
+    "trigger_recall": null,
+    "trigger_precision": null,
+    "disambiguation": null,
+    "chain_correctness": null,
+    "outcome_quality": null,
+    "variance": null,
+    "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
+  },
+  "composite": 83
+}

package/skills/shepherd/SKILL.md

@@ -1,66 +1,106 @@
 ---
 name: shepherd
 description: >
-  Monitor an already-reviewed OPEN pull request toward merge: read the CI/check rollup and the
-  branch-protection required-check set, take at most one idempotent action (re-run a flaky
-  required check, or post a status reply to a thread), then declare MERGE_READY, PENDING, or
-  escalate. Use when the user says "is PR #123 ready to merge yet?", "poll/watch the checks on
-  my PR", "the required CI job is flaky — kick off a re-run", "keep an eye on this PR until
-  it's green", "babysit the checks after /review", "shepherd PR 45", or "monitor the PR toward
-  merge (rebase if behind, --auto-rebase)". NEVER merges (the human merges in the GitHub UI),
-  edits code, or resolves review threads. Do NOT use to fix or reply-and-resolve PR feedback
-  from Greptile/CodeRabbit/SonarCloud — that is `review`; nor to open/push the PR — that is
-  `ship`; nor for the post-merge "CI green on master + close issues" check — that is `verify`;
-  nor for a general "where am I / what's in flight" report — that is `status`.
+  Own open PRs to merge-readiness — autonomously. Forge provides a singleton
+  shepherd daemon — start it with `forge shepherd daemon` — that then watches every
+  open PR, converges CI check state into kernel verdicts, re-runs flaky required
+  checks, reaps orphan watchers, and self-retires when no PRs remain; one-shot
+  passes (forge shepherd <pr>) exist for a single bounded check. Use when a PR was
+  just opened or shipped; when a session starts with open PRs (start the daemon in
+  a background shell — the singleton lease makes a duplicate start a safe no-op);
+  when the user asks "why isn't my PR merging", "what's
+  blocking the PR", "is the PR ready", "did a check fail / go red"; when asked to
+  "keep watching / keep an eye on / babysit my PRs"; or to read PR verdicts
+  (forge shepherd <pr> --pull --json, forge shepherd events). NEVER merges and
+  never resolves review threads — fixing review feedback is `review`; opening the
+  PR is `ship`; post-merge health is `verify`; general orientation is `status`.
 allowed-tools: Bash, Read, Grep, Glob
+terminal: true
+handoffs:
+  - review
 ---
 
-Run one bounded monitor pass over a pull request: read CI and check state, take at most one idempotent action, then hand off. Never merges and never resolves review threads.
+Forge owns your open PRs. A singleton daemon converges every open PR toward merge-readiness; you read its verdicts and only step in on escalations. Never merges, never resolves review threads.
 
 # Shepherd
 
-`shepherd` is a **utility command, not a workflow stage.** It automates the polling / rerun / escalation loop that today is done by hand after `/review`. It does **not** replace `/review` (which still owns semantic review and its stage transition) and does **not** perform the pre-merge doc gate (embedded in `/ship` and `/review`).
+`shepherd` is the PR-ownership utility, not a workflow stage. It has two modes over the **single `forge shepherd` verb**:
 
-## Usage
+- **Daemon (default ownership):** `forge shepherd daemon` is a machine-wide singleton for this repo. It heartbeats and converges the whole PR world every ~60s — self-registering hand-opened PRs, restarting killed watchers, reaping verified orphans, converging CI check state into kernel verdicts, retiring merged/closed PRs — then self-retires (releases the lease, kills its children, exits) once no PRs remain open. You do NOT poll by hand; the daemon does.
+- **One-shot pass:** `forge shepherd <pr>` reads one PR's state, takes at most one idempotent Tier-A action, and exits. Use it for a point-in-time question about a single PR.
+
+## Which mode? (decision rule)
+
+- User asks about **one PR, right now** ("is #212 ready?", "why is this blocked?") → **one-shot** (`forge shepherd <pr> --pull`).
+- Anything **ongoing** — "keep", "until it merges", "watch", "babysit", multiple PRs, or a session that starts with PRs already open → **ensure the daemon is running**.
+
+## Session-start ritual
+
+When a session starts and the repo has open PRs, ensure the daemon is running:
 
 ```bash
-forge shepherd <pr-number>
-forge shepherd <pr-number> --auto-rebase   # opt-in, default OFF
+forge shepherd daemon    # start it in the HARNESS BACKGROUND SHELL
 ```
 
-## Bounded-pass model (one pass = one invocation)
+The daemon is a **repo singleton** guarded by an O_EXCL lease, so you do NOT need a liveness check first — a second start when one is already running simply exits (the lease is already held). Start it in the harness background shell (Claude Code / Codex background-shell) so it is session-scoped and reaped with the session. NEVER launch a detached spawn from the agent: the detached path is Forge's bare-CLI fallback only. (Automatic per-command launch and a `forge prime` daemon-liveness line are planned follow-ups — W-S4c/W-S5 — not yet wired; until then you start the daemon explicitly as above.)
 
-Each `forge shepherd <pr>` invocation is **ONE discrete bounded pass**: it reads PR state, takes at most the allowed Tier-A action, then **exits**. It never sits in-process polling "until merge-ready."
+## Reading verdicts (the common case)
 
-This mirrors the project's documented ergonomic from `/review`, the pre-merge gate, and the Greptile process: **poll briefly, then stop and hand off.** Any pass that finds checks still pending exits as `PENDING`, and the next scheduled pass picks up where it left off.
+```bash
+forge shepherd <pr> --pull --json          # actionable payload: WHY blocked + exactly what to fix
+forge shepherd <pr> --bundle --json        # the COMPLETE read-only PR-state bundle
+forge shepherd events <pr> --since <seq>   # only the new events since sequence <seq>
+```
+
+`--pull` is strictly read-only (dry-run pass: no rerun, no rebase, no merge, no thread resolution). It returns one bounded, actionable-only payload — `blockers[]`, classified `requiredChecks`, failed-check log `failures[]` (matrix-deduped), and every unresolved `reviewThreads[]` — so you get "everything blocking this PR + what to fix" in one call. Passing checks and satisfied policy are omitted.
 
-A `--watch` affordance, if you want one, lives in an **external scheduler** (e.g. cron or a `/loop`) that re-invokes the bounded pass on an interval with debounce (>= 60s between passes, cancel-in-progress). There is no in-process infinite loop.
+### Verdict vocabulary (collapsed, W-S1)
 
-## What it never does
+| Verdict | Meaning |
+| --- | --- |
+| `MERGE_READY` | Required checks green, branch up to date — hand off to a human to merge. |
+| `PENDING` | A Tier-A action was taken, or checks are still running — await the next tick/pass. |
+| `BLOCKED` | Something actionable blocks merge (failing/missing/skipped required check, conflict, behind, unresolved threads, changes requested). Read `blockers[]`. |
+| `CI_DEAD_HEAD` | The head has no required checks running (e.g. an auto-update authored by `GITHUB_TOKEN` never re-triggered CI). Recovery is an **escalation, not an autonomous Tier-A rerun**: it needs a maintainer-provided `FORGE_PR_TOKEN` (contents + pull-requests + checks) to re-author the push so CI re-triggers. |
+| `ESCALATE` | A Tier-C condition (conflict, unreadable required set, persistent failure, oscillation, budget exhaustion). Context is posted to the PR. |
+| `HARD_STOP` | A permanent auth/scope failure retrying cannot fix — a human must widen token scope. |
 
-- **Never merges.** There is no merge action and no server-side auto-merge latch. The shepherd terminates at `MERGE_READY` and hands off to the human, who merges in the GitHub UI (mirroring the pre-merge gate's merge handoff).
-- **Never resolves review threads.** It may post a status **reply** to a thread (via the existing `.claude/scripts/review-resolve.sh reply` helper), but thread **resolution** is semantic and stays with `/review`.
+## Trigger scenario → command
 
-## Action ladder
+| Situation | Command |
+| --- | --- |
+| PR just opened / shipped | ensure `forge shepherd daemon` running |
+| Session starts, open PRs exist, daemon dead | `forge shepherd daemon` (background shell) |
+| "Why isn't my PR merging / what's blocking it" | `forge shepherd <pr> --pull` |
+| "Is the PR ready?" | `forge shepherd <pr> --pull` (read `MERGE_READY`) |
+| "A check failed / went red" | `forge shepherd <pr> --pull --json` (read `failures[]`) |
+| "Keep watching / babysit my PRs" | ensure `forge shepherd daemon` running |
+| Read incremental deltas | `forge shepherd events <pr> --since <seq>` |
 
-- **Tier-A (autonomous, idempotent, reversible):** re-run a flaky **required** check via `gh run rerun --failed` (capped by a rerun budget). Post status replies to threads (reply only).
-- **Tier-B (opt-in per-flag, default OFF):** `--auto-rebase` rebases onto the base and force-pushes with lease. Preconditions: clean working tree, HEAD unchanged during the pass. A lease rejection is a **hard-stop + escalate** — the shepherd never re-arms the lease, because doing so would clobber the concurrent human push the lease exists to protect.
-- **Tier-C (human escalation):** merge conflicts, required-check failures a rerun did not fix, an unreadable required-check set, unknown mergeability, auth/scope failures, oscillation, and budget exhaustion all stop and escalate with context posted to the PR.
+## Boundaries (kept — true of both modes)
 
-## Merge-readiness gate
+- **Never merges.** No merge action, no server-side auto-merge latch. Terminates at `MERGE_READY` and hands off — a human merges in the GitHub UI.
+- **Never resolves review threads.** It refreshes a single **sticky** status comment; thread *resolution* is semantic and stays with `review`.
+- **Action ladder.** Tier-A (autonomous, idempotent): re-run a flaky **required** check (rerun-budget capped); refresh the single **sticky** status comment — an *upsert*, never an append, so the ~60s daemon loop cannot post duplicate comments. Tier-B (opt-in, default OFF): `--auto-rebase` rebases onto base and force-pushes with lease — a lease rejection is a hard-stop, never re-armed. Tier-C: everything else escalates (incl. `CI_DEAD_HEAD` recovery, which needs the maintainer `FORGE_PR_TOKEN`).
+- **Required-check gate.** `MERGE_READY` only when the branch-protection required set is *known* and all green; if protection is unreadable, it escalates rather than guessing.
+- **HEAD-changed abort.** Before any mutating action it re-reads the head SHA and aborts if HEAD moved.
 
-Merge-ready is declared **only** when the branch-protection required-check set is **known** AND all of it is green AND the branch is not behind base. The required set is read from `gh api repos/{owner}/{repo}/branches/{base}/protection/required_status_checks`. If branch protection is unreadable (insufficient token scope, or the branch is not protected), the shepherd does **not** guess — it escalates with the readable rollup attached.
+## Adjacent skills
 
-## Concurrency & safety
+- Fixing review feedback (CodeRabbit/Greptile/human comments, resolving threads) → `review`.
+- Opening or pushing the PR → `ship`.
+- Post-merge health (CI green on main, close issues) → `verify`.
+- "Where am I / what's in flight" orientation → `status`.
 
-- The advisory `shepherd:active` marker is **not** mutual exclusion. The real guard is a per-action HEAD-SHA re-read: before any mutating action the shepherd re-reads the head SHA, and if HEAD moved since the pass started it **aborts** the action.
-- Auth taxonomy: token expiry (401) pauses and surfaces; insufficient scope (403) is a permanent **hard-stop**; a secondary rate limit (403 + `Retry-After`) honors the delay and resumes on the next pass.
+## Kill-switches
 
-## Per-harness behavior
+```bash
+FORGE_SHEPHERD_DISABLE=1        # env: makes the shepherd trigger inert (once the auto-fire wiring lands, W-S4c)
+forge gate disable rail.auto_shepherd   # config gate honored by the trigger + ship/push arming
+```
 
-- **Claude Code / Codex:** invoke `forge shepherd <pr>` directly; an external scheduler may drive repeated bounded passes.
-- **Cursor:** manually-invoked only. Run `forge shepherd <pr>` from a terminal — there is no polling-loop affordance and no hook reliance on this surface.
+Both leave the manual `forge shepherd` surface usable; they only stop the automatic daemon fire.
 
 ## 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, labels, `git`). The one local store is the per-PR journal under `.forge/pr-monitor/<repo>-<pr>/` (append-only `events.ndjson` + snapshot/consumer cursors) — the replay surface for `events --since`. The bounded one-shot pass keeps no separate local state.

package/skills/shepherd/evals/evals.json

@@ -1,30 +1,42 @@
 [
+  {
+    "query": "A PR just got shipped — keep watching it until every required check is green.",
+    "should_trigger": true
+  },
+  {
+    "query": "Why isn't my PR merging? Tell me exactly what's blocking the PR.",
+    "should_trigger": true
+  },
   {
     "query": "Is PR #212 ready to merge yet?",
     "should_trigger": true
   },
   {
-    "query": "The lint check on my PR keeps failing intermittently — kick off a re-run of the failed jobs.",
+    "query": "My PR has been sitting for an hour with no merge — poll the PR and tell me what's wrong.",
     "should_trigger": true
   },
   {
-    "query": "Keep an eye on pull request 88 and tell me when all the required checks pass.",
+    "query": "One of the checks failed on my pull request — kick off a re-run of the required job.",
     "should_trigger": true
   },
   {
-    "query": "I just wrapped up /review on this PR — babysit the checks and escalate if it isn't mergeable.",
+    "query": "Keep an eye on my open PRs and babysit them toward merge.",
     "should_trigger": true
   },
   {
-    "query": "Shepherd PR 300 and rebase it onto master if it's behind.",
+    "query": "Start the shepherd daemon so my open PRs get watched.",
     "should_trigger": true
   },
   {
-    "query": "Fix all the CodeRabbit and Greptile comments on my PR and resolve each review thread.",
-    "should_trigger": false
+    "query": "Watch the pull request and let me know when it's mergeable.",
+    "should_trigger": true
+  },
+  {
+    "query": "What's the current PR verdict on #90 — read it back for me.",
+    "should_trigger": true
   },
   {
-    "query": "The PR just merged to master — confirm CI is green there and close the linked issue.",
+    "query": "Fix all the CodeRabbit and Greptile comments on my PR and resolve each review thread.",
     "should_trigger": false
   },
   {
@@ -32,11 +44,11 @@
     "should_trigger": false
   },
   {
-    "query": "Where am I in the workflow and what work is still in flight right now?",
+    "query": "The PR merged to master — run the post-merge health check and close the linked issue.",
     "should_trigger": false
   },
   {
-    "query": "Show me the SonarCloud issues flagged on this PR.",
+    "query": "Where am I in the workflow and what work is still in flight right now?",
     "should_trigger": false
   }
 ]