@delorenj/pjangler 1.2.17 → 1.2.19

package/templates/hermes-agent/template/.scripts/providers/linear.sh

@@ -0,0 +1,176 @@
+#!/usr/bin/env sh
+# Linear ticket-provider adapter (reference implementation).
+#
+# Credentials:  LINEAR_API_KEY
+# Board binding (role.yaml `ticket_provider:`):
+#   name: linear
+#   team:    <TEAM_KEY>          e.g. DEL
+#   project: "<Project name>"    optional; scopes milestone/issue queries
+#   state_map: { in_review: "In Review", completed: "Done" }   optional overrides
+#
+# Implements the contract in lib/ticket-provider.sh. All Linear access goes
+# through GraphQL so the same envelope works in unattended runs.
+set -eu
+
+OP="${1:-}"; shift 2>/dev/null || true
+ROLE_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
+ROLE_YAML="$ROLE_DIR/role.yaml"
+
+die() { echo "linear: $*" >&2; exit 1; }
+need_key() { [ -n "${LINEAR_API_KEY:-}" ] || die "LINEAR_API_KEY is not set"; }
+
+# tp_cfg KEY — read ticket_provider.<KEY> from role.yaml (best-effort, flat).
+tp_cfg() {
+  [ -f "$ROLE_YAML" ] || return 0
+  python3 - "$ROLE_YAML" "$1" <<'PY'
+import sys, re, pathlib
+text = pathlib.Path(sys.argv[1]).read_text()
+m = re.search(r'(?ms)^ticket_provider:\s*$(.*?)(?=^\S)', text + "\n\x00")
+block = m.group(1) if m else ""
+key = sys.argv[2]
+mm = re.search(rf'(?m)^\s*{re.escape(key)}:\s*"?([^"\n]*)"?\s*$', block)
+print(mm.group(1).strip() if mm else "")
+PY
+}
+
+# pj_cfg KEY — read ticket_provider.<KEY> from the repo-root .project.json (the
+# SOT), walking up from the role dir. Preferred over role.yaml.
+pj_cfg() {
+  python3 - "$ROLE_DIR" "$1" <<'PY'
+import sys, json, pathlib
+start = pathlib.Path(sys.argv[1]).resolve(); key = sys.argv[2]
+for parent in [start, *start.parents]:
+    f = parent / ".project.json"
+    if f.is_file():
+        try: tp = (json.loads(f.read_text()).get("ticket_provider") or {})
+        except Exception: tp = {}
+        print(tp.get(key, "") if isinstance(tp, dict) else ""); break
+else:
+    print("")
+PY
+}
+
+# gql QUERY [VARS_JSON] — POST a GraphQL request, print data JSON, fail on errors.
+gql() {
+  need_key
+  _vars="${2:-}"; [ -n "$_vars" ] || _vars='{}'
+  python3 - "$1" "$_vars" <<'PY'
+import json, os, sys, urllib.request, urllib.error
+q, variables = sys.argv[1], json.loads(sys.argv[2])
+req = urllib.request.Request(
+    "https://api.linear.app/graphql",
+    data=json.dumps({"query": q, "variables": variables}).encode(),
+    headers={"Authorization": os.environ["LINEAR_API_KEY"],
+             "Content-Type": "application/json"},
+    method="POST")
+try:
+    body = json.loads(urllib.request.urlopen(req, timeout=30).read())
+except urllib.error.HTTPError as e:
+    body = json.loads(e.read() or "{}")
+except urllib.error.URLError as e:
+    print(f"linear request failed: {e}", file=sys.stderr); sys.exit(1)
+if body.get("errors"):
+    print(json.dumps(body["errors"]), file=sys.stderr); sys.exit(1)
+print(json.dumps(body.get("data") or {}))
+PY
+}
+
+TEAM="$(pj_cfg team)"; [ -n "$TEAM" ] || TEAM="$(tp_cfg team)"
+PROJECT="$(pj_cfg project)"; [ -n "$PROJECT" ] || PROJECT="$(tp_cfg project)"
+SM_IN_REVIEW="$(tp_cfg in_review)"; SM_IN_REVIEW="${SM_IN_REVIEW:-In Review}"
+SM_DONE="$(tp_cfg completed)"; SM_DONE="${SM_DONE:-Done}"
+
+# All Linear ops require the API key; fail fast and clean before any pipe.
+need_key
+
+case "$OP" in
+  resolve)
+    [ -n "$TEAM" ] || die "ticket_provider.team (Linear team key) not set in role.yaml"
+    gql 'query($k:String!){ teams(filter:{key:{eq:$k}}){nodes{id key name}} }' \
+        "$(printf '{"k":"%s"}' "$TEAM")" \
+      | python3 -c 'import sys,json; d=json.load(sys.stdin); t=(d.get("teams",{}).get("nodes") or [{}])[0]; print(json.dumps({"provider":"linear","board_id":t.get("id",""),"board_url":"https://linear.app/team/"+t.get("key","")}))'
+    ;;
+
+  active_milestone)
+    # Linear project milestones; pick the first non-completed milestone in the project.
+    gql 'query($p:String){ projects(filter:{name:{eq:$p}}){nodes{ id name projectMilestones{nodes{id name targetDate}} state }} }' \
+        "$(printf '{"p":"%s"}' "$PROJECT")" \
+      | python3 -c 'import sys,json
+d=json.load(sys.stdin); ps=d.get("projects",{}).get("nodes") or []
+p=ps[0] if ps else {}
+ms=(p.get("projectMilestones",{}) or {}).get("nodes") or []
+m=ms[0] if ms else {"id":p.get("id",""),"name":p.get("name","")}
+print(json.dumps({"id":m.get("id",""),"name":m.get("name",""),"state":p.get("state","")}))'
+    ;;
+
+  list_issues)
+    [ -n "$TEAM" ] || die "ticket_provider.team not set"
+    gql 'query($k:String!){ issues(first:100, filter:{team:{key:{eq:$k}}}){nodes{ id identifier title updatedAt url state{name type} assignee{name} }} }' \
+        "$(printf '{"k":"%s"}' "$TEAM")" \
+      | python3 -c 'import sys,json
+d=json.load(sys.stdin); out=[]
+for n in d.get("issues",{}).get("nodes") or []:
+    st=n.get("state") or {}
+    out.append({"id":n["id"],"key":n.get("identifier",""),"title":n.get("title",""),
+                "state":st.get("name",""),"state_type":st.get("type",""),
+                "updated_at":n.get("updatedAt",""),
+                "assignee":(n.get("assignee") or {}).get("name",""),"url":n.get("url","")})
+print(json.dumps(out))'
+    ;;
+
+  get_issue)
+    ID="${1:?usage: get_issue <id>}"
+    gql 'query($id:String!){ issue(id:$id){ id identifier title description state{name type} comments{nodes{id body user{name}}} } }' \
+        "$(printf '{"id":"%s"}' "$ID")" \
+      | python3 -c 'import sys,json
+d=json.load(sys.stdin); i=d.get("issue") or {}
+st=i.get("state") or {}
+cs=[{"id":c["id"],"body":c.get("body",""),"author":(c.get("user") or {}).get("name","")} for c in (i.get("comments",{}) or {}).get("nodes") or []]
+print(json.dumps({"id":i.get("id",""),"key":i.get("identifier",""),"title":i.get("title",""),
+                  "description":i.get("description",""),"acceptance":i.get("description",""),
+                  "state":st.get("name",""),"state_type":st.get("type",""),"comments":cs}))'
+    ;;
+
+  comment)
+    ID="${1:?usage: comment <id> <body>}"; BODY="${2:?usage: comment <id> <body>}"
+    gql 'mutation($id:String!,$b:String!){ commentCreate(input:{issueId:$id,body:$b}){ comment{id} success } }' \
+        "$(python3 -c 'import json,sys; print(json.dumps({"id":sys.argv[1],"b":sys.argv[2]}))' "$ID" "$BODY")" \
+      | python3 -c 'import sys,json; d=json.load(sys.stdin); print((d.get("commentCreate",{}).get("comment") or {}).get("id",""))'
+    ;;
+
+  transition)
+    ID="${1:?usage: transition <id> <normalized-state>}"; TARGET="${2:?}"
+    # Map normalized -> a concrete Linear state name, then resolve its id on the team.
+    case "$TARGET" in
+      completed)  WANT_TYPE=completed; WANT_NAME="$SM_DONE" ;;
+      in_review)  WANT_TYPE=started;   WANT_NAME="$SM_IN_REVIEW" ;;
+      started)    WANT_TYPE=started;   WANT_NAME="" ;;
+      unstarted)  WANT_TYPE=unstarted; WANT_NAME="" ;;
+      backlog)    WANT_TYPE=backlog;   WANT_NAME="" ;;
+      *) die "invalid normalized state: $TARGET" ;;
+    esac
+    STATE_ID="$(gql 'query($id:String!){ issue(id:$id){ team{ states{nodes{id name type}} } } }' \
+        "$(printf '{"id":"%s"}' "$ID")" \
+      | WANT_TYPE="$WANT_TYPE" WANT_NAME="$WANT_NAME" python3 -c 'import sys,json,os
+d=json.load(sys.stdin)
+states=((d.get("issue") or {}).get("team") or {}).get("states",{}).get("nodes") or []
+want_t=os.environ["WANT_TYPE"]; want_n=os.environ.get("WANT_NAME","")
+named=[s for s in states if want_n and s["name"].lower()==want_n.lower()]
+typed=[s for s in states if s.get("type")==want_t]
+pick=(named or typed or [{}])[0]
+print(pick.get("id",""))')"
+    [ -n "$STATE_ID" ] || die "no Linear state for normalized '$TARGET'"
+    gql 'mutation($id:String!,$s:String!){ issueUpdate(id:$id,input:{stateId:$s}){ success issue{identifier state{name}} } }' \
+        "$(python3 -c 'import json,sys; print(json.dumps({"id":sys.argv[1],"s":sys.argv[2]}))' "$ID" "$STATE_ID")" \
+      | python3 -c 'import sys,json; u=json.load(sys.stdin).get("issueUpdate",{});
+print(("ok " + (u.get("issue") or {}).get("identifier","")) if u.get("success") else "FAILED"); sys.exit(0 if u.get("success") else 1)'
+    ;;
+
+  create_board)
+    # Linear teams/projects are created by humans; the adapter resolves, not creates.
+    echo "linear: create_board is a no-op (Linear team/project created via Linear UI); using resolve" >&2
+    exec sh "$0" resolve
+    ;;
+
+  *) die "unknown op: $OP" ;;
+esac

package/templates/hermes-agent/template/.scripts/providers/plane.sh

@@ -1,11 +1,12 @@
 #!/usr/bin/env sh
 # Plane ticket-provider adapter.
 #
-# Credentials:  PLANE_API_KEY or PLANE_<WORKSPACE>_API_KEY (X-API-Key header)
+# Credentials:  PLANE_API_KEY   (X-API-Key header)
 # Endpoint:     PLANE_BASE       (default https://plane.delo.sh)
-# Board binding (repo-root .project.json `ticket_provider:`):
+# Board binding (role.yaml `ticket_provider:`):
+#   name: plane
 #   workspace: <workspace-slug>      (or env PLANE_WORKSPACE)
-#   board_id:  <project-uuid>        (set by create_board / 42-ticket-provider)
+#   project:   <project-uuid>        (set by create_board / 42-ticket-provider)
 #   state_map: { in_review: "In Review", completed: "Done" }   optional
 #
 # Plane model:  project = board, cycle = milestone, state.group in
@@ -20,21 +21,9 @@ ROLE_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
 ROLE_YAML="$ROLE_DIR/role.yaml"
 BASE="${PLANE_BASE:-https://plane.delo.sh}"
 
-FLEET_ENV="${HERMES_FLEET_ENV:-$HOME/.hermes/fleet.env}"
-if [ -f "$FLEET_ENV" ]; then
-  # shellcheck disable=SC1090
-  . "$FLEET_ENV"
-fi
-
 die() { echo "plane: $*" >&2; exit 1; }
 need_key() { [ -n "${PLANE_API_KEY:-}" ] || die "PLANE_API_KEY is not set"; }
 
-workspace_key() {
-  key="$(printf '%s' "${1:-default}" | tr '[:lower:]' '[:upper:]' | sed 's/[^A-Z0-9]/_/g')"
-  [ -n "$key" ] || key="DEFAULT"
-  printf 'PLANE_%s_API_KEY' "$key"
-}
-
 tp_cfg() {
   [ -f "$ROLE_YAML" ] || return 0
   python3 - "$ROLE_YAML" "$1" <<'PY'
@@ -65,19 +54,13 @@ else:
 PY
 }
 
-# Board binding: .project.json (SOT) first, then legacy role.yaml, then env.
+# Board binding: .project.json (SOT) first, then role.yaml, then env.
 WS="$(pj_cfg workspace)"; [ -n "$WS" ] || WS="$(tp_cfg workspace)"; WS="${WS:-${PLANE_WORKSPACE:-}}"
-PROJ="$(pj_cfg board_id)"; [ -n "$PROJ" ] || PROJ="$(tp_cfg project)"; [ -n "$PROJ" ] || PROJ="$(tp_cfg board_id)"
+PROJ="$(pj_cfg board_id)"; [ -n "$PROJ" ] || PROJ="$(tp_cfg project)"
 SM_IN_REVIEW="$(tp_cfg in_review)"; SM_IN_REVIEW="${SM_IN_REVIEW:-In Review}"
 SM_DONE="$(tp_cfg completed)"; SM_DONE="${SM_DONE:-Done}"
 API="$BASE/api/v1/workspaces/$WS"
 
-if [ -z "${PLANE_API_KEY:-}" ]; then
-  KEY="$(workspace_key "$WS")"
-  eval "PLANE_API_KEY=\${$KEY:-}"
-  export PLANE_API_KEY
-fi
-
 # api METHOD PATH [JSON_BODY] — call Plane REST, print response body.
 api() {
   need_key
@@ -85,12 +68,9 @@ api() {
   if [ -n "$body" ]; then
     curl -fsS -X "$method" "$API/$path" \
       -H "X-API-Key: $PLANE_API_KEY" -H "Content-Type: application/json" \
-      -H "User-Agent: curl/8.0" \
       -d "$body"
   else
-    curl -fsS -X "$method" "$API/$path" \
-      -H "X-API-Key: $PLANE_API_KEY" \
-      -H "User-Agent: curl/8.0"
+    curl -fsS -X "$method" "$API/$path" -H "X-API-Key: $PLANE_API_KEY"
   fi
 }
 
@@ -120,8 +100,8 @@ need_key
 
 case "$OP" in
   resolve)
-    [ -n "$WS" ] || die "workspace not set (.project.json ticket_provider.workspace or PLANE_WORKSPACE)"
-    [ -n "$PROJ" ] || die "project not set (.project.json ticket_provider.board_id; run 42-ticket-provider.sh)"
+    [ -n "$WS" ] || die "workspace not set (role.yaml ticket_provider.workspace or PLANE_WORKSPACE)"
+    [ -n "$PROJ" ] || die "project not set (run 42-ticket-provider.sh)"
     printf '{"provider":"plane","board_id":"%s","board_url":"%s/%s/projects/%s/issues/"}\n' \
       "$PROJ" "$BASE" "$WS" "$PROJ"
     ;;

package/templates/hermes-agent/template/.scripts/sentinel/docs/autonomous-delegated-review.md

@@ -13,7 +13,7 @@ actively tries to break the work, surface unmet acceptance criteria, hidden
 regressions, and drift. On a clean adversarial verdict the loop treats the
 ticket as done and moves on — through the ticket-provider adapter
 (`tp transition <id> <state>`) — and emits a BloodBank decision event carrying
-the full report. This works identically on Plane or Trello.
+the full report. This works identically on Linear, Plane, or Trello.
 
 The operator's verification is **deferred** to end-of-product QA over the review
 lane, backed by a queryable decision trail. A downstream regression rollback is
@@ -144,7 +144,7 @@ Write `<ISSUE>.review.md`; the script validates it:
 ```markdown
 # Autonomous Review Report: <ISSUE>
 ## Issue
-- Provider issue: <ISSUE>
+- Linear/Plane/Trello issue: <ISSUE>
 - Review lane reason:
 ## Reviewer
 - Reviewer agent: <independent-agent-id>

package/templates/hermes-agent/template/.scripts/sentinel/docs/continuous-ticket-orchestration.md

@@ -19,7 +19,7 @@ approve merges.
 All board access goes through the adapter (`tp`, from
 `.scripts/lib/ticket-provider.sh`) and reasons in normalized states:
 `backlog | unstarted | started | in_review | completed`. Never call the provider
-directly — the engine is identical across Plane and Trello.
+directly — the engine is identical across Linear, Plane, and Trello.
 
 ## Work-state feed
 

package/templates/hermes-agent/template/.scripts/sentinel.prompt.md.jinja

@@ -6,11 +6,6 @@ A cheap systemd heartbeat already decided this full pass is needed.
 Working repo: the git root containing this role at `agents/hermes/{{ role }}/`.
 Ticket provider: **{{ ticket_provider }}** (reached only through the adapter — see below).
 
-The configured ticket provider is the authoritative repo ticket board/SOT for
-this PM. Hermes local Kanban must NOT be an active durable task lifecycle
-surface. Local Kanban may only run as an explicitly configured ephemeral child
-execution queue and must never close/move authoritative repo tickets.
-
 You are the **{{ target_repo }} PM**, running your continuous board-reconciliation
 pass. Act autonomously, but stay inside the project contracts. Read
 `agents/hermes/{{ role }}/SOUL.md` and the engine docs under
@@ -32,7 +27,7 @@ tp transition <id> <normalized-state>  # backlog|unstarted|started|in_review|com
 ```
 
 Reason in **normalized states**, not provider terms. This pass works identically
-on Plane or Trello.
+on Linear, Plane, or Trello.
 
 ## Pass
 

package/templates/hermes-agent/template/SOUL.md.jinja

@@ -46,8 +46,8 @@ Envelope shape: CloudEvents 1.0, type `bloodbank.v1.<domain>.<entity>.<action>`,
 `source = hermes://agent/{{ agent_id }}`. The consumer in `./runtime/` already
 imports the envelope helper.
 
-You **MUST NOT** invent new event `type` values. The naming contract is owned
-by Holyfields and locked at `~/code/33GOD/bloodbank/docs/event-naming.md` —
+You **MUST NOT** invent new event `type` values. Bloodbank owns the naming
+contract at `~/code/33GOD/bloodbank/docs/event-naming.md` —
 read it before publishing a type you haven't published before.
 
 ## Role-specific behavior
@@ -55,24 +55,22 @@ read it before publishing a type you haven't published before.
 {% if role == "pm" -%}
 You are the **project manager**. You triage incoming requests from Telegram /
 Bloodbank command lanes, decompose them into discrete tasks on the
-configured ticket board, and route work to other agents in the fleet (e.g. the dev role
-on `bloodbank.cmd.v1.agent.{{ target_repo }}-dev.task.assign`). You do not
-write application code. You do not approve merges.
-
-The configured ticket provider (`{{ ticket_provider }}`) is the authoritative
-repo ticket board/SOT for this PM. Hermes local Kanban must NOT be an active
-durable task lifecycle surface. The kanban toolset is removed from the PM's cli
-surface. Local Kanban may only run as an explicitly configured ephemeral child
-execution queue and must never close/move authoritative repo tickets.
+Plane board, and route work to other agents in the fleet (e.g. the dev role
+on `bloodbank.cmd.v1.agent.task.assign` with
+`data.target_agent_id = {{ target_repo }}-dev`). You do not write application
+code. You do not approve merges.
 
 Default execution workflow for implementation delivery: use
-`subagent-driven-development` in provider-ticket-orchestrated implementation mode
+`subagent-driven-development` in kanban-orchestrated codex mode
 (WIP=1, spec review gate, quality review gate).
 
 Decision events you commonly emit:
-- `bloodbank.v1.repo.{{ target_repo }}.decision.recorded`
-- `bloodbank.v1.repo.{{ target_repo }}.intake.triaged`
-- `bloodbank.v1.repo.{{ target_repo }}.task.created`
+- `bloodbank.v1.repo.decision.recorded`
+- `bloodbank.v1.repo.intake.triaged`
+- `bloodbank.v1.repo.task.created`
+
+Put `repo = {{ target_repo }}` in event data; never insert repo or agent
+identifiers into Bloodbank type or subject tokens.
 
 Template-governor command contract:
 - If operator says `update template to capture <X>`, run `hermes-pm-template-maintenance` workflow:
@@ -87,17 +85,17 @@ write tests, run the project's `mise run test` or equivalent, open PRs, and
 respond to review comments. You do not merge — that's the reviewer's call.
 
 Events you commonly emit:
-- `bloodbank.v1.repo.{{ target_repo }}.code.committed`
-- `bloodbank.v1.repo.{{ target_repo }}.test.run.completed`
-- `bloodbank.v1.repo.{{ target_repo }}.pr.opened`
+- `bloodbank.v1.repo.code.committed`
+- `bloodbank.v1.repo.test.completed`
+- `bloodbank.v1.repo.pr.opened`
 {%- elif role == "review" -%}
 You are the **reviewer**. You read PRs critically, check against the
 project's CONTRIBUTING and AGENTS.md, and either approve or request changes.
 You hold the merge gate for non-trivial changes.
 
 Events:
-- `bloodbank.v1.repo.{{ target_repo }}.review.completed`
-- `bloodbank.v1.repo.{{ target_repo }}.pr.merged`
+- `bloodbank.v1.repo.review.completed`
+- `bloodbank.v1.repo.pr.merged`
 {%- else -%}
 You operate as the **{{ role }}** agent for this repo. Define your contract
 in this file (this section), then publish a `bloodbank.v1.agent.contract.
@@ -112,7 +110,7 @@ declared` event so the fleet knows what to route to you.
 - **Hostnames**: Use `*.delo.sh` for external/cross-machine access (resolved
   via Cloudflare Tunnel), `localhost` for same-host, Docker network service
   names for container-to-container, Tailscale for private machine-to-machine.
-- **Ticketing**: Always include the configured provider's ticket reference in commit messages.
+- **Plane**: Always include a Plane ticket reference in commit messages.
 
 ## Memory hygiene
 

package/templates/hermes-agent/template/role.yaml.jinja

@@ -21,16 +21,47 @@ profile: {{ agent_id }}
 telegram:
   bot_username: "{{ bot_handle }}"
 
-# Ticket-provider adapter preference (plane | trello).
-# Repo-owned board identity lives in repo-root .project.json, not in this role.
+# Ticket-provider binding (linear | plane | trello).
+# The heartbeat reconciliation pass talks ONLY to this via .scripts/lib/ticket-provider.sh;
+# swapping providers is a one-line change here. Filled in by 42-ticket-provider.sh.
 ticket_provider:
   name: {{ ticket_provider }}
+  board_id: ""
+  board_url: ""
+{%- if ticket_provider == 'linear' %}
+  team: ""        # Linear team key, e.g. DEL  (set before first sentinel run)
+  project: ""     # optional Linear project name to scope milestones/issues
+{%- elif ticket_provider == 'plane' %}
+  workspace: "{{ plane_workspace }}"
+  project: ""     # Plane project uuid (set by 42-ticket-provider.sh)
+{%- elif ticket_provider == 'trello' %}
+  board: ""       # Trello board id (set by 42-ticket-provider.sh)
+{%- endif %}
+  # Optional normalized-state name overrides for non-standard boards.
+  in_review: ""   # e.g. "In Review"
+  completed: ""   # e.g. "Done"
+
+# Board-reconciliation knobs for the heartbeat sentinel pass.
+reconcile:
+  enabled: false             # heartbeat runs the autonomous board-reconciliation pass ONLY when true; default off = checkpoint-only
+  grace_hours: 0             # 0 = no human-approval wait (adversarially-reviewed review-lane = done); set >0 to require a wait
+  auto_review: true          # autonomous adversarial review (act, do not wait) on/off
+
+# Plane project (1:1 with this agent) — retained for fleet-registry back-compat.
+plane:
+  # Empty -> resolved from ~/.config/hermes-agent-template/config.toml [plane].workspace
+  workspace: "{{ plane_workspace }}"
+  # identifier is set by .scripts/42-ticket-provider.sh after creation (plane only)
+  identifier: ""
 
 # Bloodbank wiring (consumed + produced subjects).
 bloodbank:
   subscribe:
-    - "bloodbank.evt.v1.repo.{{ target_repo }}.>"
-    - "bloodbank.cmd.v1.agent.{{ agent_id }}.>"
+    - "bloodbank.evt.v1.repo.>"
+    - "bloodbank.cmd.v1.agent.>"
+  routing:
+    repo: "{{ target_repo }}"
+    target_agent_id: "{{ agent_id }}"
   producer: "hermes-agent:{{ agent_id }}"
 
 # Runtime repo (git-tracked HERMES_HOME, auto-checkpointed).

package/templates/hermes-agent/tests/test_bloodbank_consumer_contract.py

@@ -0,0 +1,138 @@
+import importlib.util
+import os
+import pathlib
+import re
+import sys
+import tempfile
+import types
+import unittest
+
+
+ROOT = pathlib.Path(__file__).resolve().parents[1]
+CONSUMER_PATH = ROOT / "runtime-scaffold" / "bloodbank-consumer.py"
+GENERATED_CONSUMER_PATH = ROOT / "template" / ".runtime-scaffold" / "bloodbank-consumer.py"
+
+
+def load_consumer():
+    sys.modules.setdefault("nats", types.ModuleType("nats"))
+    spec = importlib.util.spec_from_file_location("bloodbank_consumer_contract", CONSUMER_PATH)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    module.AGENT_ID = "demo-pm"
+    module.REPO = "demo"
+    module.PRODUCER = "hermes-agent:demo-pm"
+    module.SOURCE = "hermes://agent/demo-pm"
+    return module
+
+
+class BloodbankConsumerContractTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.temp_home = tempfile.TemporaryDirectory()
+        cls.previous_home = os.environ.get("HERMES_HOME")
+        os.environ["HERMES_HOME"] = cls.temp_home.name
+        cls.consumer = load_consumer()
+
+    @classmethod
+    def tearDownClass(cls):
+        if cls.previous_home is None:
+            os.environ.pop("HERMES_HOME", None)
+        else:
+            os.environ["HERMES_HOME"] = cls.previous_home
+        cls.temp_home.cleanup()
+
+    def test_scaffold_copies_stay_identical(self):
+        self.assertEqual(CONSUMER_PATH.read_bytes(), GENERATED_CONSUMER_PATH.read_bytes())
+
+    def test_subscriptions_use_fixed_canonical_routes(self):
+        self.assertEqual(
+            self.consumer.SUBJECTS,
+            ["bloodbank.evt.v1.repo.>", "bloodbank.cmd.v1.agent.>"],
+        )
+        self.assertNotIn("demo", ".".join(self.consumer.SUBJECTS))
+        self.assertNotIn("demo-pm", ".".join(self.consumer.SUBJECTS))
+
+    def test_envelope_keeps_identity_out_of_type_and_subject(self):
+        envelope = self.consumer.build_envelope(
+            "bloodbank.v1.repo.issue.updated",
+            {"repo": "demo", "issue": "PJAN-1"},
+        )
+        self.assertEqual(envelope["type"], "bloodbank.v1.repo.issue.updated")
+        self.assertEqual(envelope["subject"], "bloodbank.evt.v1.repo.issue.updated")
+        self.assertEqual(envelope["data"]["repo"], "demo")
+        self.assertEqual(envelope["actor"]["agent_id"], "demo-pm")
+        self.assertEqual(envelope["source"], "hermes://agent/demo-pm")
+        self.assertNotIn("demo", envelope["type"])
+        self.assertNotIn("demo", envelope["subject"])
+        with self.assertRaisesRegex(ValueError, r"bloodbank\.v1"):
+            self.consumer.build_envelope(
+                "bloodbank.v2.repo.issue.updated",
+                {"repo": "demo"},
+            )
+
+    def test_repo_events_route_by_data_repo(self):
+        subject = "bloodbank.evt.v1.repo.issue.updated"
+        envelope = self.consumer.build_envelope(
+            "bloodbank.v1.repo.issue.updated",
+            {"repo": "demo"},
+        )
+        self.assertTrue(self.consumer._is_for_consumer(subject, envelope))
+        envelope["data"]["repo"] = "another-repo"
+        self.assertFalse(self.consumer._is_for_consumer(subject, envelope))
+
+    def test_agent_commands_route_by_target_agent_id(self):
+        subject = "bloodbank.cmd.v1.agent.task.assign"
+        envelope = self.consumer.build_envelope(
+            "bloodbank.v1.agent.task.assign",
+            {"target_agent_id": "demo-pm"},
+            kind="command",
+        )
+        self.assertTrue(self.consumer._is_for_consumer(subject, envelope))
+        envelope["data"]["target_agent_id"] = "other-agent"
+        self.assertFalse(self.consumer._is_for_consumer(subject, envelope))
+
+    def test_rejects_identifier_bearing_or_mismatched_routes(self):
+        envelope = self.consumer.build_envelope(
+            "bloodbank.v1.repo.issue.updated",
+            {"repo": "demo"},
+        )
+        self.assertFalse(
+            self.consumer._is_for_consumer(
+                "bloodbank.evt.v1.repo.demo.issue.updated",
+                envelope,
+            )
+        )
+        self.assertFalse(
+            self.consumer._is_for_consumer(
+                "bloodbank.evt.v1.repo.issue.created",
+                envelope,
+            )
+        )
+        envelope["kind"] = "command"
+        self.assertFalse(
+            self.consumer._is_for_consumer(
+                "bloodbank.evt.v1.repo.issue.updated",
+                envelope,
+            )
+        )
+
+    def test_generated_contract_docs_do_not_put_identifiers_in_routes(self):
+        coupled_paths = [
+            ROOT / "docs" / "architecture.md",
+            ROOT / "docs" / "operations.md",
+            ROOT / "template" / "SOUL.md.jinja",
+            ROOT / "template" / "role.yaml.jinja",
+            ROOT / "runtime-scaffold" / "memories" / "MEMORY.md",
+            ROOT / "template" / ".runtime-scaffold" / "memories" / "MEMORY.md",
+        ]
+        forbidden = re.compile(
+            r"bloodbank\.(?:v1\.repo|evt\.v1\.repo|cmd\.v1\.agent)\."
+            r"(?:\{\{|<repo>|<agent_id>)"
+        )
+        for path in coupled_paths:
+            with self.subTest(path=path):
+                self.assertIsNone(forbidden.search(path.read_text()))
+
+
+if __name__ == "__main__":
+    unittest.main()

package/templates/hermes-agent/docs/bloodbank-gateway.md

@@ -1,57 +0,0 @@
-# Bloodbank Gateway
-
-Bloodbank command events should be a first-class Hermes gateway, not an inbox
-directory that a later heartbeat drains.
-
-## Goal
-
-Make this true:
-
-```
-Telegram message -> Hermes gateway -> agent turn queue -> agent acts
-Bloodbank command -> Hermes gateway -> agent turn queue -> agent acts
-Web message      -> Hermes gateway -> agent turn queue -> agent acts
-```
-
-The transport changes; the agent turn contract does not.
-
-## Current State
-
-`runtime-scaffold/bloodbank-consumer.py` subscribes to NATS subjects and writes
-JSON files under `bloodbank-inbox/`. That proves subscription, envelope parsing,
-and durable audit capture, but it is not command execution. It can accumulate
-files while the agent never acts.
-
-## Target Contract
-
-- The Bloodbank gateway subscribes to `bloodbank.cmd.v1.agent.<agent_id>.>`.
-- Each command event is converted into the same internal Hermes message/turn
-  shape used by Telegram and web gateways.
-- Hermes owns backpressure: if the agent is busy, the command waits in the
-  message queue until the agent can act.
-- The gateway emits lifecycle events:
-  - received
-  - accepted or rejected
-  - turn_started
-  - turn_completed or turn_failed
-- Replies use the incoming `correlationid` and `reply_to`/reply subject when
-  present.
-- Idempotency uses the CloudEvent `id`; duplicate events do not create duplicate
-  turns.
-
-## Required Work
-
-1. Add a Hermes transport adapter for Bloodbank/NATS.
-2. Define a command payload schema that maps cleanly to a user prompt plus
-   metadata (`actor`, `source`, `priority`, `correlationid`, `reply_to`).
-3. Replace the file-inbox consumer service with `hermes gateway bloodbank run`
-   or equivalent.
-4. Keep optional audit persistence, but make it observational only.
-5. Add smoke tests that publish a NATS command and assert that a Hermes turn is
-   created, processed, and acknowledged.
-
-## Non-Goals
-
-- No heartbeat inbox drain.
-- No polling directory as the command execution mechanism.
-- No per-agent one-off consumer logic.