@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.c18009cd

package/integrations/hermes/docs/issue-1162-grilling.md

@@ -0,0 +1,197 @@
+# Issue #1162 — Grilling summary: `/gsd new-milestone` via Hermes
+
+Source: `grill-with-docs` + `grilling` + `domain-modeling` skills on issue #1162.
+This is the shared understanding the interview reached — the design tree walked
+branch-by-branch with a decision at each node. Implementation should conform to
+this; deviations should re-open the corresponding question, not silently diverge.
+
+Glossary for every term below lives in [`../CONTEXT.md`](../CONTEXT.md).
+
+---
+
+## The one-line design
+
+Add a `/gsd new-milestone <spec>` slash command that spawns
+`gsd headless new-milestone` as a **plugin-owned subprocess**, fires-and-forgets
+an ack, drives lifecycle (blocker/terminal) notifications from the subprocess's
+stream-json stdout, and hands execution off to the **existing, untouched**
+`/gsd auto` path. No `--auto` chaining, no new MCP tool, no TS-side changes.
+
+---
+
+## Decision tree (Q1–Q9)
+
+### Q1 — Mechanism & transport → **(A) Slash command → CLI subprocess**
+- New `_cmd_new_milestone` in `GsdCommandRouter`. Shells out to
+  `gsd headless new-milestone --context-text <spec>`.
+- **Not** a Hermes skill (B), **not** a new MCP `gsd_create_milestone` tool (C).
+- Rationale: the plugin already has a proven direct-CLI pattern (`progress()`
+  calls `gsd read progress --json`); `new-milestone` is even more naturally a
+  CLI call (it bootstraps `.gsd/`, has a 10-min timeout, manages its own RPC
+  child). An MCP tool would re-implement what the CLI already does, and the
+  upstream lease-layer co-run issue (CHANGELOG:509, open) makes advertising
+  `gsd_create_milestone` over MCP actively unsafe to every MCP client.
+- A later Hermes skill (B) can wrap the same client method with zero rework.
+
+### Q2 — Co-run safety gate → **(A) Local supervisor state only**
+- Reject if `SupervisorContext.state in (RUNNING, BLOCKED)` before spawning.
+- **Not** a server-side cross-binding check (B). Documented limitation: a
+  session started by *another* plugin instance / a headless run outside this
+  plugin is invisible to the local guard; the CLI's own lease check is the
+  backstop.
+- Rationale: the plugin can only authoritatively own its own state; a
+  server-side "is anything running?" check is itself racy and adds a new query
+  path to design and test.
+
+### Q3 — Run model → **(A) Fire-and-track via the existing async-push model**
+- Return "🚀 Milestone creation started (session X)" immediately; push
+  blocker/terminal notifications from a background stream-reader.
+- **Not** a synchronous blocking call (rejected after discovering the plugin is
+  fundamentally async-push — `_cmd_auto` already works this way; the target
+  chat platforms don't hold request/response open for minutes).
+- *(Note: "reuse `SupervisorFsm` unchanged" was initially proposed under this
+  label but does NOT work — see A1 below.)*
+
+### Q3 follow-up — How to drive the fire-and-track → **(A1) Client-owned subprocess, direct stream→notification**
+- `GsdMcpClient` spawns `gsd headless new-milestone --output-format stream-json`
+  on a background thread, reads stdout line-by-line, captures
+  `init_result.sessionId`, and on terminal/blocker events calls
+  `NotificationService` directly.
+- `SupervisorContext` is **shared state** (written by the stream-reader, read by
+  `/gsd status`, `/gsd cancel`, the co-run gate); the `SupervisorFsm` poll loop
+  is **not** reused for the milestone path (its `_tick` calls `gsd_status`,
+  which can't see our subprocess).
+- Rationale: the stream *is* the lifecycle signal; polling would be a lossy
+  proxy for events we already get deterministically. Reuses
+  `NotificationService` and `SupervisorContext` unchanged.
+
+### Q4 — Cancellation → **(A) Local PID ownership + direct SIGTERM**
+- `GsdMcpClient` holds the `subprocess.Popen` handle; `cancel_milestone()` calls
+  `proc.terminate()` directly. `_cmd_cancel` routes to it when a milestone proc
+  is active.
+- **Not** a new `.gsd/milestone.lock` pid file for the MCP backstop (B) — that
+  crosses the Python/TS boundary and inverts ownership. **Not** "no cancel during
+  planning" (C) — a stuck planning run needs an escape hatch.
+- Discovered: MCP `cancelSessionByDir`'s `auto.lock` pid backstop does NOT find
+  our planning subprocess (no `auto.lock` exists during planning — it's an
+  auto-loop concept). So local ownership is required, not optional.
+- Plus explicit supervisor stop on cancel (immediate confirmation, don't wait
+  for next poll tick).
+
+### Q5 — Scope: `--auto` (chained execution)? → **No. Planning-only.**
+- The plugin creates the milestone and hands off; execution is `/gsd auto`'s job.
+- `/gsd auto` already has a robust path (MCP `gsd_execute` → self-healing poll
+  supervisor). Chaining `--auto` would duplicate that with a stateful
+  stream-reader over hours (fragile) instead of the proven poll loop.
+- **Boundary clarification:** this plugin (`gsd-pi/integrations/hermes/`) is the
+  chat gateway. One-shot `new-milestone --auto` is gsd-core's terminal surface,
+  not the gateway's.
+- `/gsd new-milestone --auto` is **rejected at the command level** with a message
+  pointing to the two-step flow.
+
+### Q6 — Input shape → **Bare positional, with `--file` escape**
+- `/gsd new-milestone <spec text>` → `--context-text` (matches `/gsd reply`).
+- `/gsd new-milestone --file <path>` → `--context <file>` (explicit opt-in).
+- **Not** auto-detect path-vs-text (heuristic misroutes on collision — rule #5).
+- **Not** `--description "..."` flag form (issue's example used it, but the bare
+  positional matches the sibling command users already know).
+
+### Q7 — Output → **(A) Bounded summary via `gsd_query` at completion, with (B) as graceful fallback**
+- Immediate ack: "🚀 Milestone creation started for `<project>`."
+- Completion push: bounded summary — milestone id, slice count, task count,
+  one-line next step ("Run `/gsd auto` to start."). Built from
+  `gsd_query {projectDir, query: "milestones"}` after exit-0.
+- Fallback: if the query comes back empty/missing after exit-0, degrade to
+  "✅ Milestone created. Run `/gsd status` for details."
+- **Trust exit-0; no defensive re-querying.** If exit-0 lies about flush state,
+  that's a gsd-core bug to fix at the source, not a leak for the plugin to patch
+  with a racy retry loop.
+- Error/blocked cases route through existing `notify_terminal`/`notify_blocker`
+  unchanged.
+
+### Q8 — Failure modes
+| # | Mode | Disposition |
+|---|---|---|
+| 1 | Active auto session (co-run) | Reject before spawn; fail closed |
+| 2 | No project bound | Reuse `BindingError` path (zero new code) |
+| 3 | Empty spec | Usage message (matches `_cmd_reply`/`_cmd_bind`) |
+| 4 | Spec too long for `--context-text` | Surface `E2BIG`/`OSError`; point to `--file` |
+| 5 | Planning errors (non-zero exit) | `notify_terminal(status, error)` via existing path |
+| 6 | Planning hits a blocker | `notify_blocker`; reply via **client-owned stdin** (see below) |
+| 7 | `--file` missing/unreadable | Validate before spawn |
+| 8 | Stream-reader thread/pipe dies | Best-effort: set FAILED, `notify_terminal("failed", "stream lost — run /gsd cancel")`. **No watchdog.** Cancel is the escape hatch. |
+| 9 | Plugin restart mid-planning | **Documented limitation.** Orphaned subprocess survives; invisible after restart (same as existing supervisor's restart-blindness). |
+| 10 | User passes `--auto` | Reject at command level (see Q5) |
+
+**Blocker replies (#6) — client-owned, not MCP-routed.** `gsd_resolve_blocker`
+calls `sessionManager.resolveBlocker` which looks up the MCP server's *own*
+sessions map — our subprocess isn't there, so it throws "Session not found".
+Because we own the subprocess's stdin (A1), `/gsd reply` for a planning blocker
+writes the response to *our* subprocess's stdin via a new
+`respond_to_milestone_blocker(response)` method. `_cmd_reply` gets one branch:
+if a milestone subprocess with a pending blocker is active, route locally; else
+fall through to the existing MCP `resolve_blocker` path.
+
+### Q9 — Cross-effects on existing commands
+- **`_cmd_cancel`** — MUST change: add milestone-subprocess branch routing to
+  local `cancel_milestone()` (SIGTERM) when one is active. *Required.*
+- **`_cmd_auto`** — MUST change: add symmetric co-run guard (reject if
+  `SupervisorContext` shows an active milestone run, point to `/gsd cancel`).
+  *Required* — without it, `/gsd auto` during milestone planning silently
+  re-exposes the unsafe co-run (the MCP server's "Session already active"
+  rejection does NOT fire for our planning subprocess, since it's not registered
+  and writes no `auto.lock`). Rule #12 (fail loud) over rule #3 (surgical) here.
+- **`/gsd status`** — leave alone. Reads disk honestly; the Q3-accepted planning
+  progress gap means it may show stale/partial state early on. The completion
+  notification is the real "done" signal.
+- **`/gsd reply`** — additive branch only (Q8 #6); core MCP path untouched.
+- **`SupervisorFsm`** — untouched (A1 uses a separate stream-reader driver).
+- **TS MCP server** — untouched (no new tools).
+
+---
+
+## Implementation surface (additive unless noted)
+
+**`gsd_client.py`** — new methods + state:
+- `self._milestone_proc: subprocess.Popen | None`
+- `create_milestone(project_dir, *, context_text=None, context_file=None) -> str` —
+  spawns `gsd headless new-milestone --output-format stream-json`, starts the
+  stream-reader thread, returns `sessionId` (captured from `init_result`). Throws
+  on co-run guard / missing spec.
+- `_milestone_stream_loop(proc)` — reads stdout JSONL; on `init_result` captures
+  `sessionId`; on blocker event → `notify_blocker` + sets
+  `SupervisorContext.pending_blocker_id`; on terminal/exit → `notify_terminal` +
+  sets `SupervisorContext.state`.
+- `cancel_milestone()` — `proc.terminate()` + cleanup.
+- `respond_to_milestone_blocker(response)` — writes UI-response to proc stdin.
+- `milestone_active()` predicate for the co-run gate.
+
+**`commands.py`** — new handler + two modifications:
+- `_cmd_new_milestone(rest)` — the new command (guard, parse, spawn, ack).
+- `_cmd_cancel` (modify) — milestone-subprocess branch.
+- `_cmd_auto` (modify) — symmetric co-run guard.
+- `_cmd_reply` (modify) — milestone-blocker branch (additive).
+- `_cmd_help` (modify) — list `new-milestone`.
+
+**`__init__.py`** — wire the new client methods / supervisor notifications if
+the constructor surface changes (likely no change — `GsdMcpClient` already has
+`config`, and `NotificationService` is already injected).
+
+**Tests** (new, matching existing `tests/test_*.py` patterns):
+- `test_new_milestone_command.py` — guard (co-run both ways), input parsing
+  (bare text, `--file`, empty, `--auto` rejected), spawn + ack.
+- extend `test_gsd_client_cache.py` or new `test_milestone_client.py` —
+  stream-reader captures sessionId from `init_result`; blocker event →
+  `notify_blocker`; terminal → `notify_terminal`; cancel SIGTERMs the proc;
+  blocker reply writes stdin.
+- extend cancel/reply tests for the new branches.
+
+---
+
+## Explicitly OUT of scope (v1)
+
+- `--auto` chaining (execution stays with `/gsd auto`).
+- Cross-instance / server-side co-run coordination (Q2 limitation).
+- Plugin-restart recovery of an orphaned planning subprocess (Q8 #9).
+- A Hermes skill (issue's Option B) — additive follow-on, wraps the same client.
+- Any TS-side / MCP-server change.

package/integrations/hermes/docs/setup.md

@@ -0,0 +1,276 @@
+# Hermes × GSD Gateway Setup Checklist
+
+Manual validation before releasing `open-gsd-hermes` 1.2.x. Complete **local preflight** first, then run the **Slack** or **Telegram** gateway walkthrough on a real GSD project.
+
+---
+
+## Quick start
+
+```bash
+# End-user path after installing/upgrading @opengsd/gsd-pi
+gsd hermes install --project /absolute/path/to/your/project
+hermes plugins list                                  # open-gsd-hermes should be enabled
+hermes gateway restart                               # or restart your Hermes CLI/gateway process
+
+# Source-checkout validation path
+npm run build:core                                   # dist/loader.js for read CLI
+pip install -e integrations/hermes[dev]
+bash integrations/hermes/scripts/preflight.sh        # local gates (no Hermes)
+```
+
+Record results in the [Sign-off](#sign-off) section at the bottom.
+
+---
+
+## Part 1 — Local preflight (no gateway)
+
+Run before touching Slack or Telegram.
+
+| Step | Command / check | Pass criteria |
+|------|-----------------|---------------|
+| P1 | `bash integrations/hermes/scripts/preflight.sh` | All checks ✓, exit 0 |
+| P2 | `gsd --version` | Semver in `>=2.53,<3` (or your configured `gsd_version_min`) |
+| P3 | `which gsd-mcp-server` | Binary on PATH or path set in `~/.hermes/gsd.yaml` |
+| P4 | `gsd read progress --json --project <your-project>` | JSON with `"integration_version": 1` and `activeMilestone` |
+| P5 | Project has `.gsd/` (or `.planning/`) with `STATE.md` | `read progress` shows phase/milestone |
+
+**Fixture smoke (optional):**
+
+```bash
+node dist/loader.js read progress --json \
+  --project integrations/hermes/tests/fixtures/minimal-project
+# Expect activeMilestone.id == "M001"
+```
+
+---
+
+## Part 2 — Hermes gateway setup
+
+### Install plugin
+
+Preferred end-user path:
+
+```bash
+gsd hermes install --project /absolute/path/to/your/project
+hermes plugins list   # should show open-gsd-hermes enabled
+```
+
+Manual source-checkout path:
+
+```bash
+pip install -e /path/to/gsd-pi/integrations/hermes
+HERMES_HOME="${HERMES_HOME:-$HOME/.hermes}"
+mkdir -p "$HERMES_HOME/plugins"
+cp -R /path/to/gsd-pi/integrations/hermes "$HERMES_HOME/plugins/open-gsd-hermes"
+hermes plugins enable open-gsd-hermes
+hermes plugins list   # should show open-gsd-hermes enabled
+```
+
+Restart the Hermes gateway after enabling the plugin.
+
+### Configuration (`~/.hermes/gsd.yaml`)
+
+```yaml
+gsd:
+  # Use absolute paths in production
+  cli_path: /usr/local/bin/gsd          # or an executable wrapper around dist/loader.js
+  mcp_server_path: /usr/local/bin/gsd-mcp-server
+  credential_source: gsd                # 6a: GSD-managed API keys
+  default_project: ~/code/myapp         # optional fallback
+  poll_interval_seconds: 12
+  cache_ttl_seconds: 45
+  mcp_read_timeout_seconds: 60          # per-response MCP read timeout
+  notification_level: normal            # quiet | normal | verbose
+  bindings:
+    slack:
+      C0123456789: ~/code/myapp         # Slack channel ID (see below)
+    telegram:
+      "123456789": ~/code/myapp         # Telegram chat ID (see below)
+```
+
+**Binding tiers (first match wins):** cron explicit → slash argument → `/gsd bind` session binding → channel map → `default_project` → cwd heuristic.
+
+**MCP read timeout:** `gsd.mcp_read_timeout_seconds` defaults to `60` seconds and bounds each response read from the `gsd-mcp-server` sidecar. Increase it for very slow projects, machines, or network-backed filesystems where Hermes reports MCP response timeouts but the same GSD command eventually completes locally; lower it only when you prefer faster failure detection. When the timeout fires, the plugin terminates the stuck sidecar and the next project-scoped call starts a fresh server in the bound project directory.
+
+**Credentials:** With `credential_source: gsd`, ensure GSD’s normal provider keys are configured (`~/.gsd/` or env). Hermes passthrough (`credential_source: hermes`) is 6b+.
+
+### Verify plugin loaded
+
+- [ ] Gateway logs show no `GsdVersionError` on startup
+- [ ] `/gsd help` (or `/gsd` with no args) returns the command list
+- [ ] No MCP spawn errors in logs when running `/gsd status`
+
+---
+
+## Part 3 — Slack gateway walkthrough
+
+Use a **dedicated test channel** (not `#general`). Invite the Hermes bot.
+
+### Slack-specific config
+
+1. Copy the **channel ID** (right-click channel → *View channel details* → bottom of About, or from URL `C…`).
+2. Add to `~/.hermes/gsd.yaml` under `bindings.slack` **or** skip and use `/gsd bind` only.
+3. Ensure the Hermes Slack app has slash-command / message permissions for that channel.
+
+**Session key shape (notifications):** `agent:main:slack:{chat_type}:{channel_id}`
+
+Supervisor push uses `ctx.dispatch_tool("send_message", …)` — **not** `inject_message`.
+
+### Slack checklist
+
+#### Bind
+
+| # | Action | Expected result | ✓ |
+|---|--------|-----------------|---|
+| S1 | `/gsd bind /absolute/path/to/project` | `Bound to \`/absolute/path/to/project\`` | [ ] |
+| S2 | `/gsd status` | Snapshot with `## GSD Project Snapshot`, phase, active milestone/slice | [ ] |
+| S3 | Wrong path: `/gsd bind /nonexistent` | Error or bind failure (path not a GSD project) | [ ] |
+
+#### Auto + supervision
+
+| # | Action | Expected result | ✓ |
+|---|--------|-----------------|---|
+| S4 | `/gsd auto` | `Started GSD auto mode (session \`<uuid>\`)` | [ ] |
+| S5 | Wait for unit transition (or set `notification_level: verbose`) | Push message: `📋 GSD: milestone → …` or slice/task transition | [ ] |
+| S6 | Send a normal message to the agent (not a slash command) | Agent context includes GSD snapshot (check Hermes debug/logs if available) | [ ] |
+
+#### Blocker reply
+
+Trigger a blocker (project with a pending gate, or auto mode that hits `AskUserQuestion`).
+
+| # | Action | Expected result | ✓ |
+|---|--------|-----------------|---|
+| S7 | Auto blocks | Push: `🚧 GSD blocker: …` with `/gsd reply` hint | [ ] |
+| S8 | `/gsd reply <your answer>` | `Blocker response sent.` | [ ] |
+| S9 | `/gsd status` or wait for resume | Session no longer blocked; auto continues | [ ] |
+
+#### Cancel
+
+| # | Action | Expected result | ✓ |
+|---|--------|-----------------|---|
+| S10 | `/gsd auto` (new session) | Session id returned | [ ] |
+| S11 | `/gsd cancel` while running | `Cancel requested.` then `⏹ GSD session cancelled.` push | [ ] |
+| S12 | After cancel | No further transition notifications | [ ] |
+
+#### Fail closed
+
+| # | Action | Expected result | ✓ |
+|---|--------|-----------------|---|
+| S13 | New Slack thread/channel with **no** bind/default | `/gsd auto` → `No GSD project bound. Use \`/gsd bind <path>\`…` | [ ] |
+
+---
+
+## Part 4 — Telegram gateway walkthrough
+
+Use a **private test chat** or small group where you control noise.
+
+### Telegram-specific config
+
+1. Get **chat ID** (message `@userinfobot`, or Bot API `getUpdates` after messaging the bot).
+2. Add under `bindings.telegram` as a string key, **or** use `/gsd bind` per chat.
+3. Ensure the Hermes Telegram bot is running and can receive commands in that chat.
+
+**Session key shape:** `agent:main:telegram:{chat_type}:{chat_id}`
+
+### Telegram checklist
+
+Repeat the same flow as Slack (steps **S1–S13**), substituting Telegram commands:
+
+| # | Action | Expected result | ✓ |
+|---|--------|-----------------|---|
+| T1 | `/gsd bind /absolute/path/to/project` | Bound confirmation | [ ] |
+| T2 | `/gsd status` | GSD snapshot in reply | [ ] |
+| T3 | `/gsd auto` | Session id in reply | [ ] |
+| T4 | Transition notification | `📋 GSD: …` in chat | [ ] |
+| T5 | Blocker + `/gsd reply <text>` | Blocker push, then `Blocker response sent.` | [ ] |
+| T6 | `/gsd cancel` | Cancel confirmation + `⏹` push | [ ] |
+| T7 | Unbound chat `/gsd auto` | Fail-closed bind error | [ ] |
+
+**Telegram notes:**
+
+- Long replies may split; confirm the **session id** line appears in the first chunk.
+- In groups, ensure the bot receives commands (privacy mode / mention rules per Hermes config).
+
+---
+
+## Part 5 — Notification levels (6b)
+
+Verify on **one** platform (Slack or Telegram):
+
+| `notification_level` | Transitions | Blockers | Terminal (done/fail/cancel) |
+|----------------------|-------------|----------|------------------------------|
+| `quiet` | suppressed | ✓ | ✓ |
+| `normal` (default) | ✓ | ✓ | ✓ |
+| `verbose` | ✓ (all) | ✓ | ✓ |
+
+- [ ] `quiet`: no `📋 GSD:` transition spam during auto
+- [ ] `normal`: transitions + blockers + terminal messages appear
+- [ ] `verbose`: same as normal (reserved for future detail)
+
+---
+
+## Part 6 — Cron + read CLI (optional, post-6a)
+
+| # | Check | Pass | ✓ |
+|---|-------|------|---|
+| C1 | `hermes-gsd-cron ~/code/myapp` | Exit 0 or documented code when queue empty | [ ] |
+| C2 | Hermes cron job with `deliver:` | Completion/failure posted to home channel | [ ] |
+| C3 | `gsd read progress --json --project <path>` | `integration_version: 1` | [ ] |
+| C4 | Memory prefetch (6c) | Agent/memory hook includes GSD memories for query ≥2 chars | [ ] |
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| `GsdVersionError` on start | `gsd` outside semver range | Set `gsd_version_min` in `gsd.yaml` or upgrade gsd |
+| MCP spawn fails | Wrong `mcp_server_path` | `which gsd-mcp-server`; set absolute path |
+| `/gsd status` hangs | MCP sidecar stuck | Check `GSD_CLI_PATH`; restart gateway; kill orphaned `gsd-mcp-server` |
+| MCP response times out after 60s | Slow project or filesystem, or wedged sidecar | Confirm the command locally; tune `mcp_read_timeout_seconds` if it completes after 60s |
+| No push notifications | Invalid session key / target | Key must match `agent:main:{platform}:{chat_type}:{chat_id}`; check Hermes gateway logs |
+| Notifications in CLI but not Slack | `DeliveryTarget.from_session_key` returned None | Run checklist in **gateway** mode, not CLI-only |
+| Cancel ignored | Stale session id | `/gsd cancel` uses `gsd_cancel_by_project` fallback when no session id |
+| Bind works, auto fails | Missing API credentials | Configure GSD provider keys (`credential_source: gsd`) |
+| Empty snapshot | No `.gsd/STATE.md` | Run `/gsd status` in interactive GSD once to generate state |
+| Channel map ignored | Wrong binding key | Use Slack **channel ID** (`C…`), not display name `#foo` |
+
+### Debug commands
+
+```bash
+# Local
+bash integrations/hermes/scripts/preflight.sh
+gsd read progress --json --project "$PROJECT"
+
+# MCP sidecar (manual)
+GSD_CLI_PATH=gsd gsd-mcp-server   # should stay running; Ctrl+C to stop
+```
+
+---
+
+## Sign-off
+
+Complete after running **Slack** and/or **Telegram** walkthroughs.
+
+| Field | Value |
+|-------|-------|
+| Date | |
+| Tester | |
+| `gsd --version` | |
+| `open-gsd-hermes` version | |
+| Hermes version | |
+| Platform validated | [ ] Slack  [ ] Telegram |
+| Preflight script | [ ] pass |
+| S1–S13 (Slack) | [ ] all pass |
+| T1–T7 (Telegram) | [ ] all pass |
+| Blocker round-trip | [ ] pass |
+| Cancel + no ghost notifications | [ ] pass |
+| Fail closed (unbound chat) | [ ] pass |
+
+**Release gate:** All checked items for at least **one** chat platform before tagging `open-gsd-hermes` 1.0.x.
+
+---
+
+## Upstream Hermes PR
+
+See [`upstream-hermes-pr.md`](upstream-hermes-pr.md) for documentation PR steps to Nous Research Hermes repo.

package/integrations/hermes/docs/upstream-hermes-pr.md

@@ -0,0 +1,40 @@
+# Upstream Hermes Documentation PR (6c)
+
+Open GSD does **not** transfer plugin ownership to Nous Research. Submit a documentation-only PR to the Hermes Agent repository.
+
+## PR title
+
+`docs: add GSD Pi integration guide (open-gsd-hermes)`
+
+## Files to add/change
+
+1. **`docs/integrations/gsd-pi.md`** — overview linking to this monorepo and PyPI package
+2. **`docs/examples/gsd-config.yaml`** — example `~/.hermes/gsd.yaml` snippet
+3. **`docs/guides/build-a-hermes-plugin.md`** — cross-link note: use `pre_llm_call` for snapshots, not `ContextEngine`
+
+## Example config snippet
+
+```yaml
+plugins:
+  - open-gsd-hermes
+
+gsd:
+  cli_path: gsd
+  mcp_server_path: gsd-mcp-server
+  credential_source: gsd
+  default_project: ~/projects/my-app
+```
+
+## Version pairing table
+
+| open-gsd-hermes | gsd |
+|-----------------|-----|
+| 1.0.x | >=2.51,<3 |
+| 1.1.x | >=2.52,<3 |
+| 1.2.x | >=2.53,<3 |
+
+## Reviewer notes
+
+- Orchestration uses **`gsd-mcp-server`**, not `gsd --mode mcp`
+- Gateway notifications use **`send_message`** dispatch, not `inject_message`
+- Blocker resolution: **`/gsd reply`** (primary); optional thread capture in 6c

package/integrations/hermes/open_gsd_hermes/__init__.py

@@ -0,0 +1,105 @@
+"""open-gsd-hermes — Hermes Agent plugin for GSD Pi integration."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from open_gsd_hermes.binding import SessionBindStore
+from open_gsd_hermes.commands import GsdCommandRouter
+from open_gsd_hermes.config import GsdConfig, load_config
+from open_gsd_hermes.credentials import CredentialPassthrough
+from open_gsd_hermes.gsd_client import GsdMcpClient
+from open_gsd_hermes.inject import make_pre_llm_call_handler
+from open_gsd_hermes.memory import GsdMemoryProvider
+from open_gsd_hermes.notifications import NotificationService
+from open_gsd_hermes.supervisor import SupervisorContext, SupervisorFsm
+from open_gsd_hermes.types import BindingContext, DeliveryTarget, PluginContext
+
+
+def register(ctx: PluginContext) -> None:
+    """Hermes plugin entry point."""
+    config = load_config()
+    client = GsdMcpClient(config)
+    bind_store = SessionBindStore()
+
+    session_key = os.environ.get(
+        "HERMES_SESSION_KEY", "agent:main:cli:direct:local"
+    )
+    binding_ctx = BindingContext(cwd=os.getcwd())
+    supervisor_ctx = SupervisorContext()
+
+    def get_session_key() -> str:
+        return session_key
+
+    def get_binding_ctx() -> BindingContext:
+        return binding_ctx
+
+    def get_supervisor_ctx() -> SupervisorContext:
+        return supervisor_ctx
+
+    def set_supervisor_ctx(sctx: SupervisorContext) -> None:
+        nonlocal supervisor_ctx
+        supervisor_ctx = sctx
+
+    delivery_target: DeliveryTarget | None = DeliveryTarget.from_session_key(
+        session_key
+    )
+
+    def get_target() -> DeliveryTarget | None:
+        return delivery_target
+
+    def get_platform_channel() -> tuple[str | None, str | None]:
+        t = get_target()
+        if t:
+            return t.platform, t.chat_id
+        return None, None
+
+    notifications = NotificationService(ctx, config, get_target)
+    supervisor = SupervisorFsm(
+        config,
+        client,
+        notifications,
+        get_supervisor_ctx,
+        set_supervisor_ctx,
+    )
+
+    router = GsdCommandRouter(
+        config,
+        client,
+        bind_store,
+        supervisor,
+        get_session_key,
+        get_binding_ctx,
+        get_supervisor_ctx,
+        set_supervisor_ctx,
+        get_platform_channel,
+        notifications,
+    )
+
+    ctx.register_hook(
+        "pre_llm_call",
+        make_pre_llm_call_handler(config, client, router._binding_ctx),
+    )
+    ctx.register_command("gsd", router.handle)
+
+    memory_provider = GsdMemoryProvider(config, client)
+    if hasattr(ctx, "register_memory_provider"):
+        ctx.register_memory_provider(memory_provider)
+
+    # Validate credential config at startup
+    creds = CredentialPassthrough(config.credential_source)
+    for warning in creds.validate():
+        if hasattr(ctx, "log_warning"):
+            ctx.log_warning(warning)  # type: ignore[attr-defined]
+
+    # Expose for tests
+    register._state = {  # type: ignore[attr-defined]
+        "config": config,
+        "client": client,
+        "router": router,
+        "supervisor": supervisor,
+    }
+
+
+__all__ = ["register", "GsdConfig", "load_config"]