forge-workflow 0.0.9 → 0.1.0-beta.2

package/skills/claim-safety/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: claim-safety
+description: >
+  Claim a Forge issue and then PROVE you hold the live lease before you touch it, using `forge
+  issue owns <id>` (exit 0 iff you hold the single unexpired lease). Use this whenever winning
+  the claim matters: right after `forge claim`, before you `dev`/edit/`close`/`release` a
+  claimed issue, when two agents or a subagent fan-out contend for the same work, or before
+  any irreversible step. A claim's `ok:true` does NOT prove you won — duplicate replays return
+  it and expired leases get reclaimed; only `owns` proves it, so re-verify before
+  close/release. Trigger on "claim this issue safely", "did I actually win the lease",
+  "verify/prove ownership", "claim conflict", "two agents grabbed the same issue", "check I
+  still own it before closing", or before ANY mutation of a claimed issue. NOT for plain
+  single-issue create/update/close/comment with no ownership question (that is issue-basics),
+  and NOT for read-only selecting or ranking the next ready issue without claiming (that is
+  triage-ready).
+allowed-tools: Read, Bash(forge:*)
+---
+
+# Claim safety — claim, then prove you own the lease
+
+Claiming is not owning. The Forge kernel keys a claim's idempotency on
+`claim.create:<issue_id>:<actor>`, so a **same-key duplicate replay returns
+`ok:true`** echoing the *current* call's `claim_id`. A genuine cross-actor
+conflict returns `ok:false` (the partial-UNIQUE active-lease index guarantees one
+lease) — but `ok:true` **alone does not prove sole ownership**. A live lease can
+also be **reclaimed on expiry** (an expired lease is superseded by the next
+claimant). Therefore every worker MUST verify ownership before mutating a claimed
+issue, and RE-verify before `close`/`release`.
+
+This is a reusable, standalone procedure: any skill or agent that mutates a
+claimed issue embeds it (it is NOT folded into one orchestrator).
+
+## The verification primitive
+
+```bash
+forge issue owns <id>          # exit 0 iff YOU hold the live lease; non-zero otherwise
+forge issue owns <id> --json   # { ok:true, data:{ owned, claimed_by, expired, actor, expires_at } }
+```
+
+`owns` resolves your actor the same way the kernel does — `FORGE_ACTOR` →
+`FORGE_SESSION_ID` → default `forge` — then reports `owned:true` iff you hold the
+**single active claim** AND that lease **has not expired**. It exits `0` when you
+own it and non-zero (conflict, code 4) when you do not, with a clear "you do not
+own the lease for `<id>` (held by `<actor>`)" message. It is a strict READ — it
+never mutates kernel state. (`data.claimed_by` is lease-derived; there is no
+`claims` command.)
+
+## Procedure
+
+1. **Select** work — `forge issue ready --json` (see the `triage-ready` skill).
+   Never claim epics/decisions or defer-windowed items.
+2. **Claim** — `FORGE_ACTOR=<your-actor> forge claim <id>`. Always run under a
+   distinct actor so a losing claim reaches the conflict guard instead of
+   collapsing to a shared-actor duplicate.
+3. **Prove ownership BEFORE working** — `forge issue owns <id>`.
+   - **exit 0 (OWNED)** → the lease is yours; proceed to work.
+   - **non-zero (NOT OWNED)** → you lost the race, or your claim collapsed to a
+     foreign/duplicate-collapsed claim. Do NOT work the issue. **Reselect** via
+     `forge issue ready --json` and start over at step 1.
+4. **Work** the issue (`dev`/edit/etc.).
+5. **RE-verify before `close`/`release`** — a live lease can be reclaimed on
+   expiry while you worked. Run `forge issue owns <id>` again:
+   - **OWNED** → `forge release check --target <release-ref> --json` (release-readiness; omit `--target` to use the project default), then
+     `forge close <id> --reason "…"` or `forge release <id>`.
+   - **NOT OWNED** → the lease was reclaimed (likely expired). Do NOT close/
+     release someone else's lease; reselect and, if the work is still needed,
+     re-claim and reconcile.
+
+## Contract (what each result means)
+
+| `forge claim` result | Meaning | Action |
+|----------------------|---------|--------|
+| `ok:false` (conflict, code 4) | A live lease is held by another actor | Reselect (`ready`) |
+| `ok:true` | Provisionally yours — **not proof** (duplicate replays also return ok:true) | **Run `forge issue owns <id>`** |
+
+| `forge issue owns` | Meaning | Action |
+|--------------------|---------|--------|
+| exit 0, `owned:true` | You hold the live, unexpired lease | Work / close / release |
+| non-zero, `owned:false` | Someone else holds it, or your lease expired | Reselect; never mutate |
+
+## Fork points
+
+- **Actor source** — how `<your-actor>` is derived (`FORGE_ACTOR` explicit id →
+  `FORGE_SESSION_ID` → default `forge`). Use a distinct per-agent actor so
+  contending claims reach the conflict guard rather than collapsing to a duplicate.
+- **Expiry / lease TTL** — whether claims carry an `expires_at` and how long;
+  `owns` treats an expired lease as NOT owned (it can be reclaimed).
+- **Re-verify cadence** — verify after claim and again before `close`/`release`;
+  a longer task may re-verify more often (e.g. before each irreversible step).
+- **Reselection policy** — on NOT-OWNED, how the next item is chosen (ranking /
+  filters live in the `triage-ready` skill).
+- **Fail-closed posture** — with no usable clock/state, treat ownership as NOT
+  proven (mirror the readiness model's "no usable clock ⇒ not workable").
+
+## Reliability notes
+
+- A genuine cross-actor conflict returns `ok:false` — there is no phantom
+  `ok:true`-on-conflict. The real hazards are (a) a duplicate replay's `ok:true`
+  and (b) expiry-driven reclaim. `owns` closes both.
+- Full multi-agent safety depends on the actor-identity kernel fix (distinct
+  actors per agent, kernel `d71a824b`): without distinct actors, two agents
+  share one idempotency key and `owns` cannot tell them apart.

package/skills/claim-safety/evals/evals.json

@@ -0,0 +1,46 @@
+[
+  {
+    "query": "I just ran forge claim on forge-abc — how do I make sure the lease is really mine before I start editing?",
+    "should_trigger": true
+  },
+  {
+    "query": "Two of my agents may have grabbed the same issue at once — how do I tell which one actually holds it?",
+    "should_trigger": true
+  },
+  {
+    "query": "Before I close this ticket, confirm nobody reclaimed it while I was working.",
+    "should_trigger": true
+  },
+  {
+    "query": "My claim came back ok:true but I'm not convinced I won the race. Can I trust that?",
+    "should_trigger": true
+  },
+  {
+    "query": "Prove I own forge-42 before the subagent starts mutating it.",
+    "should_trigger": true
+  },
+  {
+    "query": "The lease might have expired mid-task — check I still own it before I release.",
+    "should_trigger": true
+  },
+  {
+    "query": "What's the next ready issue I should pick up?",
+    "should_trigger": false
+  },
+  {
+    "query": "Create a feature issue titled 'Add CSV export'.",
+    "should_trigger": false
+  },
+  {
+    "query": "Close forge-19 with reason 'shipped in PR 88'.",
+    "should_trigger": false
+  },
+  {
+    "query": "Take forge-30 all the way through to a PR.",
+    "should_trigger": false
+  },
+  {
+    "query": "Implement the failing auth tests for this task.",
+    "should_trigger": false
+  }
+]

package/{.github/prompts/dev.prompt.md → skills/dev/SKILL.md}

@@ -1,14 +1,25 @@
 ---
 name: dev
-description: Subagent-driven TDD implementation per task from /plan task list
-tools: []
+description: >
+  Forge DEV stage — implement an already-planned /plan task list into committed, test-backed
+  code. Reads tasks.md + plan.md, then drives each task through a subagent TDD loop
+  (implementer → spec-compliance reviewer → code-quality reviewer) with RED-GREEN-REFACTOR,
+  HARD-GATE evidence checks, and a spec-gap decision score. Use when a plan and task list
+  already exist and it is time to implement — triggers: "/dev", "start the dev stage", "build
+  the tasks", "implement tasks.md test-first", "run the implementer/reviewer TDD loop", "write
+  the code for the planned tasks one by one", "work through the task list with subagents".
+  Per-task coding ONLY. Do NOT use for creating the design doc or task list (that is plan),
+  for the post-build type-check/lint/security/test gate (validate), for pushing the branch or
+  opening the PR (ship), for addressing PR review feedback (review), or for orchestrating
+  several stages / taking an issue end-to-end to a merged PR (smith).
+allowed-tools: Bash, Read, Write, Edit, Grep, Glob
 ---
 
 Implement each task from the /plan task list using a subagent-driven loop: implementer → spec compliance reviewer → code quality reviewer per task.
 
 # Dev
 
-This command reads the task list created by `/plan` and implements each task using a three-stage subagent loop. TDD is enforced inside each implementer subagent.
+This skill reads the task list created by `/plan` and implements each task using a three-stage subagent loop. TDD is enforced inside each implementer subagent.
 
 ## Usage
 
@@ -24,19 +35,19 @@ This command reads the task list created by `/plan` and implements each task usi
 
 ```bash
 # Find task list and design doc
-ls docs/plans/
+ls docs/work/
 ```
 
 Read:
-- **Task list**: `docs/plans/YYYY-MM-DD-<slug>-tasks.md` — extract ALL task text upfront
-- **Design doc**: `docs/plans/YYYY-MM-DD-<slug>-design.md` — including ambiguity policy section
+- **Task list**: `docs/work/YYYY-MM-DD-<slug>/tasks.md` — extract ALL task text upfront
+- **Design doc**: `docs/work/YYYY-MM-DD-<slug>/plan.md` — including ambiguity policy section
 
 ### Step 2: Create decisions log
 
 Create an empty decisions log at the start of every /dev session:
 
 ```bash
-# docs/plans/YYYY-MM-DD-<slug>-decisions.md
+# docs/work/YYYY-MM-DD-<slug>/decisions.md
 ```
 
 Format for each entry:
@@ -71,11 +82,11 @@ Do NOT write any code until ALL confirmed:
 Before starting the per-task loop, check for cross-developer conflicts:
 
 ```bash
-# Auto-sync to get latest team state
-bash scripts/sync-utils.sh auto-sync
+# Auto-sync to get latest team state (non-blocking)
+forge sync || true
 
-# Check for conflicts with the current beads issue
-bash scripts/conflict-detect.sh --issue <beads-id>
+# Check for conflicts with the current Forge issue
+bash scripts/conflict-detect.sh --issue <forge-id>
 ```
 
 If exit code 2 (validation error): show error message, abort — do not show conflict prompt.
@@ -84,7 +95,7 @@ If exit code 1 (conflicts found):
 - Display the conflict output to the developer
 - Ask: "Other developers are working in overlapping areas. Proceed anyway? (y/n)"
 - If `n`: exit cleanly, no side effects
-- If `y`: log override via `bd comments add <id> "Conflict override: proceeding despite overlap with <conflicting-issues>"`, then continue to Per-Task Loop
+- If `y`: log override via `forge comment <id> "Conflict override: proceeding despite overlap with <conflicting-issues>"`, then continue to Per-Task Loop
 - Audit: record conflict override per OWASP A09
 
 If exit code 0: proceed silently to Per-Task Loop.
@@ -194,7 +205,7 @@ Reviewer checks:
 - Structure: functions not too long, proper separation of concerns
 - Duplication: no copy-paste that could be extracted
 - Test coverage: tests cover happy path and at least one error path
-- No magic numbers, no commented-out code, no TODO without a Beads issue
+- No magic numbers, no commented-out code, no TODO without a Forge issue
 
 If quality issues found: implementer fixes → re-review → repeat until ✅
 
@@ -213,7 +224,7 @@ Do NOT mark task complete or move to next task until ALL confirmed in this sessi
 4. Run it fresh — show the actual output. "Last run was fine" is not evidence.
 5. Tests run fresh — actual output shows passing.
 6. Implementer has committed (git log shows the commit).
-7. `bash scripts/beads-context.sh update-progress <id> <task-num> <total> "<title>" <commit-sha> <test-count> <gate-count>` ran successfully (exit code 0). If it fails: STOP. Show error. Do not proceed to next task.
+7. Progress recorded on the Forge issue — `forge comment <id> "task <task-num>/<total> done: <title> (<commit-sha>, <test-count> tests, <gate-count> gates)"` ran successfully (exit code 0). The Forge comment is the kernel-native record. If the recording command errors: STOP, show the error, do not proceed to the next task.
 
 Forbidden phrases (these are not evidence):
 - "should pass"
@@ -274,15 +285,18 @@ Do NOT declare /dev complete until:
 </HARD-GATE>
 ```
 
-### Beads update
+### Record stage transition
 
 ```bash
-bash scripts/beads-context.sh validate <id>
-bash scripts/beads-context.sh stage-transition <id> dev validate \
-  --summary "<N tasks done, M decision gates fired>" \
-  --decisions "<key spec gaps and how they were resolved>" \
-  --artifacts "<changed source files and test files>" \
-  --next "<validation priorities — lint issues, type concerns>"
+# Confirm the issue carries design + acceptance context.
+forge issue show <id>
+
+# Record the dev→validate transition kernel-natively (Stage:/Summary:/Decisions:/Artifacts:/Next: envelope).
+forge comment <id> "Stage: dev complete → ready for validate
+Summary: <N tasks done, M decision gates fired>
+Decisions: <key spec gaps and how they were resolved>
+Artifacts: <changed source files and test files>
+Next: <validation priorities — lint issues, type concerns>"
 ```
 
 ---
@@ -299,43 +313,23 @@ Document the gate count in the final commit message.
 
 ---
 
-## Example Output (all tasks complete)
+## Dynamic Output
 
-```
-✓ Task 1: Types and interfaces — COMPLETE
-  Spec: ✅  Quality: ✅  Tests: 4/4 passing  Commit: abc1234
-  Decision gates: 0
-
-✓ Task 2: Validation logic — COMPLETE
-  Spec: ✅  Quality: ✅  Tests: 8/8 passing  Commit: def5678
-  Decision gates: 1 (PROCEED, score 2 — documented in decisions log)
-
-✓ Task 3: API endpoint — COMPLETE
-  Spec: ✅  Quality: ✅  Tests: 6/6 passing  Commit: ghi9012
-  Decision gates: 0
-
-✓ Final code review: ✅ (coherent, consistent, correctly integrated)
+The completion summary is generated from the live task list, decisions log, Forge issue state, commits, and validation output at runtime. Do not copy a static example into this skill file; run `/dev` to view the current task/status summary.
 
-✓ Decisions log: docs/plans/2026-02-26-stripe-billing-decisions.md
-  - Decision 1: RESOLVED (score 2, proceeded with conservative choice)
-  - Decision gates fired: 1 (plan quality: Good)
-
-✓ Beads updated: forge-xyz → implementation complete
+## Integration with Workflow
 
-Ready for /validate
 ```
+Utility: /status  -> Understand current context before starting
 
-## Integration with Workflow
+Default template:
+  /dev       -> Implement each task with subagent-driven TDD (you are here)
+  /validate  -> Type check, lint, tests, security
+  /ship      -> Push + create PR
+  /review    -> Address PR feedback
+  /verify    -> Post-merge health check
 
-```
-Utility: /status     → Understand current context before starting
-Stage 1: /plan       → Design intent → research → branch + worktree + task list
-Stage 2: /dev        → Implement each task with subagent-driven TDD (you are here)
-Stage 3: /validate      → Type check, lint, tests, security — all fresh output
-Stage 4: /ship       → Push + create PR
-Stage 5: /review     → Address GitHub Actions, Greptile, SonarCloud
-Stage 6: /premerge   → Update docs, hand off PR to user
-Stage 7: /verify     → Post-merge CI check on main
+Pre-merge gate: doc updates + CI-green checkpoint embedded in /ship and /review (not a separate stage).
 ```
 
 ## Tips

package/skills/dev/evals/evals.json

@@ -0,0 +1,50 @@
+[
+  {
+    "query": "/dev",
+    "should_trigger": true
+  },
+  {
+    "query": "The plan and task list are done — start implementing the tasks one at a time, tests first.",
+    "should_trigger": true
+  },
+  {
+    "query": "Run the implementer then the spec and quality reviewer subagents over each task in tasks.md",
+    "should_trigger": true
+  },
+  {
+    "query": "Implement the already-planned tasks one at a time, red-green-refactor each",
+    "should_trigger": true
+  },
+  {
+    "query": "Time to write the code for the planned tasks and TDD each one in this worktree",
+    "should_trigger": true
+  },
+  {
+    "query": "Work through tasks.md subagent by subagent until every task is committed and reviewed",
+    "should_trigger": true
+  },
+  {
+    "query": "Set up the branch, worktree, and TDD task list for this new feature",
+    "should_trigger": false
+  },
+  {
+    "query": "Type-check, lint, and run the full test suite before I open the PR",
+    "should_trigger": false
+  },
+  {
+    "query": "Push the validated branch and open the pull request",
+    "should_trigger": false
+  },
+  {
+    "query": "The PR has open review threads from the bots — fix each finding, reply, and mark them resolved.",
+    "should_trigger": false
+  },
+  {
+    "query": "Grab the next ready issue and drive it all the way to a merged PR",
+    "should_trigger": false
+  },
+  {
+    "query": "Which workflow stage am I on and what work is in flight right now?",
+    "should_trigger": false
+  }
+]

package/skills/hermes-forge/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: hermes-forge
+description: >
+  Hermes⇄Forge boundary: Hermes CONSUMES Forge state, never a second source of truth. Use
+  whenever a Hermes session runs on a Forge repo: at session start, before acting on an issue,
+  or when you need CURRENT state. Read state ONLY via `forge orient` / `forge recap
+  <issue-id>` (bounded JSON envelope), citing each source's `path`/`authority`; never
+  reconstruct it from raw stores or kernel internals. Writeback ONLY via `forge
+  comment`/`update`/`create`; NEVER leak Hermes profile or session memory into Forge state.
+  Triggers: "orient me / current project state", "where did this fact come from, cite it",
+  "orient came back truncated", "persist a decision into Forge", "safe to store in kernel
+  state?". NOT the Forge session router over stage skills (kernel), NOT the human "what stage
+  am I in" report (status), NOT everyday issue create/update/close/search CRUD (issue-basics),
+  NOT ranking the next ready issue (triage-ready), NOT live PR monitoring (shepherd—outside
+  Hermes, unseen by orient).
+compatibility: >
+  Requires the Forge CLI (`forge`) on PATH in a Forge-initialized repo. Install
+  path — like every Forge skill pack (e.g. parallel-deep-research,
+  sonarcloud-analysis) this is delivered by the unified Skills CLI; run
+  `skills sync` to install it into `.hermes/skills/hermes-forge/`. (`forge setup`
+  initializes the skills registry via `skills init` but does not sync packs to
+  agents.) Read-only orientation works anywhere; writeback requires a Forge
+  Kernel issue backend. CLI-only — no direct file or profile writes into Forge
+  state.
+metadata:
+  author: forge
+  version: "1.0.0"
+  roadmap: forge-2agy.9.7.x
+---
+
+# Hermes ⇄ Forge consumption contract
+
+Hermes is a *consumer* of Forge project state, not an owner of it. This skill
+defines how a Hermes session reads, cites, and writes back to a Forge project
+without ever becoming a second source of truth.
+
+The boundary between what Forge owns and what Hermes owns is specified in the
+Forge repo at `docs/reference/HERMES_INTEGRATION.md` (repo-relative path — this
+skill is synced to `.hermes/skills/hermes-forge/`, so relative links would not
+resolve from the installed location).
+
+## When to use
+
+- At the start of any Hermes session on a Forge repo (orientation).
+- Before acting on a specific issue (issue recap).
+- Whenever you need current project state — never reconstruct it from raw files.
+
+## Authority: orient / recap are the only state source
+
+The Forge Kernel is the single source of truth. Hermes obtains project state
+**exclusively** through two thin CLI wrappers and must not infer state by
+reading raw issue stores, design files, or kernel internals directly:
+
+```bash
+forge orient --json                # bounded project orientation (envelope)
+forge orient --budget 4000 --json
+forge recap <issue-id> --json      # bounded per-issue recap (envelope)
+```
+
+`forge orient` and `forge recap <issue-id>` emit the deterministic JSON envelope
+described below (assembly `deterministic-file-assembly-v1`). Parse the JSON; do
+not screen-scrape the human text form.
+
+> Note: `forge recap` always requires an issue id — bare `forge recap --json`
+> (no id) prints its usage and exits non-zero rather than returning a summary.
+> Use `forge orient` for project-level orientation, or `forge recap <issue-id>`
+> for a single issue; both emit the deterministic envelope.
+
+### Envelope shape
+
+| Field | Meaning |
+| --- | --- |
+| `schema_version` | Contract version (currently `1`). Reject unknown majors. |
+| `kind` | `orientation`, `issue_recap`, or `prime`. |
+| `generated_at` | Assembly timestamp. |
+| `assembly` | `deterministic-file-assembly-v1` — same inputs ⇒ same output. |
+| `token_budget` | Budget accounting (see below). |
+| `sections[]` | Ordered content blocks, each independently cited. |
+| `sources[]` | Deduplicated provenance across all sections. |
+| `next_commands[]` | Suggested follow-up `forge` commands. Prefer these for navigation. |
+
+Each `sections[]` entry: `{ id, title, content, sources, truncated, estimated_tokens }`.
+
+## Token budget
+
+`forge orient` / `forge recap <issue-id>` are bounded so they fit a context
+window deterministically.
+
+- Default budget: **2000** estimated tokens. Minimum honored: **40**.
+- Estimation is approximate: `token_budget.approximate === true`,
+  `token_budget.chars_per_token === 4`.
+- `token_budget.requested` is what you asked for; `token_budget.used` is the
+  estimate actually emitted.
+- Raise the ceiling with `--budget N` when you need more depth; do not retry
+  blindly — request a specific larger budget.
+
+## Citation & provenance model
+
+Every fact Hermes surfaces to a user MUST be attributable. Each section carries
+`sources: [{ path, source_kind, authority, role }]`:
+
+- `path` — the file the content came from.
+- `source_kind` — the kind of artifact (e.g. design, decision, claim, queue).
+- `authority` — how authoritative the source is. Prefer higher-authority
+  sources when two sources conflict; surface the conflict rather than silently
+  picking one.
+- `role` — the role the source plays in the section.
+
+When Hermes states a project fact, cite at least the `path` and `authority` of
+the backing source. The top-level `sources[]` is the deduplicated set for the
+whole payload.
+
+## Truncation policy
+
+Truncation is deterministic, never random:
+
+- Non-preserved sections are trimmed in the order given by
+  `token_budget.truncation_order`; when the budget is exhausted, sections later
+  in that order are trimmed first. Preserved sections are kept whole and trimmed
+  only as a last resort if the payload is still over budget. The authoritative
+  per-section signal is each section's `truncated` flag and `estimated_tokens` —
+  there is no per-section `priority` field; the overall trim order is
+  `token_budget.truncation_order`.
+- A trimmed section ends with the literal marker
+  `[truncated deterministically by token budget]` and has `truncated: true`.
+- `token_budget.truncated === true` means the payload as a whole was trimmed.
+
+Treat any `truncated` section as **incomplete**. Do not present a truncated
+section as exhaustive; if completeness matters, re-request with a higher
+`--budget` or recap the specific issue.
+
+## Writeback path: Hermes → Forge Kernel
+
+Evidence and decisions discovered during a Hermes session flow back into the
+Forge Kernel **only** through Forge CLI commands. Use the issue command surface
+documented in the Forge repo at
+`docs/reference/forge-kernel-issue-command-contract.md`:
+
+```bash
+forge comment <id> <body...>   # attach evidence, a decision, or a note to an issue
+forge update <id...> [flags]   # update issue state/fields
+forge create [title] [flags]   # open a new issue for follow-up work
+```
+
+> Note: `forge audit` is verify-only (`forge audit verify`) and does **not**
+> append evidence — record evidence as an issue comment via `forge comment`.
+
+These writes land in the Forge Kernel issue store, where they become part of the
+issue's durable history (view them via the issue itself, e.g. `forge show <id>`).
+Note the read/write asymmetry: the bounded `forge orient` / `forge recap`
+envelope is assembled from project docs, `docs/work` artifacts, and the issue
+summary — it surfaces issue/design/decision state but does **not** echo
+individual issue comments back. Do not assume evidence added via `forge comment`
+reappears verbatim in the next orient/recap payload; it lives in the issue
+history, reachable from the issue record.
+
+## No-profile-write guard (hard boundary)
+
+Hermes **MUST NOT write Hermes profile** state, conversation memory, or any
+Hermes-native artifact into Forge Kernel state — not into kernel storage, not
+into design/decision files, not into the issue backend. Hermes-native memory
+stays in Hermes' own store.
+
+- ✅ Read state via `forge orient` / `forge recap`.
+- ✅ Write evidence/decisions via `forge comment` / `forge update`.
+- ❌ Never persist Hermes profile/session memory into Forge Kernel state.
+- ❌ Never edit Forge state files directly to record Hermes-side context.
+
+If a piece of context only matters to Hermes, it belongs in Hermes-native
+memory. If it is a project fact, decision, or evidence item, write it through
+the Forge CLI so it becomes part of the shared, cited source of truth.
+
+## PR shepherd (external scheduler, not orientation)
+
+The PR shepherd runs **outside** Hermes. An external scheduler invokes
+`forge shepherd <pr>` as discrete bounded passes — each pass reads CI/check
+state, takes at most one idempotent action (re-run a flaky required check), or
+escalates, then exits. It **never merges** (the human merges in the GitHub UI)
+and **never resolves review threads**.
+
+Hermes does not run the shepherd and does not learn shepherd progress through
+`forge orient` (which is deterministic-source orientation with no live PR
+awareness). Shepherd progress is durable on the **PR itself** — its comments and
+labels. When a Hermes session needs PR/CI status, read the PR directly; do not
+expect `orient` to carry it.

package/skills/hermes-forge/evals/evals.json

@@ -0,0 +1,46 @@
+[
+  {
+    "query": "I just started a Hermes session on this Forge repo — get me oriented on where the project stands before I touch anything.",
+    "should_trigger": true
+  },
+  {
+    "query": "The forge orient envelope came back with the active-work section flagged truncated. Can I treat that as the full list, or do I need to pull more?",
+    "should_trigger": true
+  },
+  {
+    "query": "Before I tell the user which approach we settled on, I need to point at the exact source file and how authoritative it is — where does that decision come from?",
+    "should_trigger": true
+  },
+  {
+    "query": "I uncovered a design decision in this session that the team needs to keep. What's the correct way to write it back into Forge without dragging my Hermes notes into kernel state?",
+    "should_trigger": true
+  },
+  {
+    "query": "Default orientation is clipping the decisions section at 2000 tokens — give me more headroom.",
+    "should_trigger": true
+  },
+  {
+    "query": "Don't rebuild the project picture by grepping the design docs yourself — go through the proper bounded orient/recap surface instead.",
+    "should_trigger": true
+  },
+  {
+    "query": "Which workflow stage am I sitting in right now, and has any of my work gone stale?",
+    "should_trigger": false
+  },
+  {
+    "query": "I'm kicking off a Forge session in Claude — which stage skill do I run to start planning a new feature?",
+    "should_trigger": false
+  },
+  {
+    "query": "Watch PR #418, rerun the flaky required check if it trips, and ping me when it's ready to merge.",
+    "should_trigger": false
+  },
+  {
+    "query": "Open a bug issue for the checkout timeout, set priority 1, and add a note about the repro steps.",
+    "should_trigger": false
+  },
+  {
+    "query": "What's the highest-priority ready issue I should pick up next?",
+    "should_trigger": false
+  }
+]