@delorenj/pjangler 1.1.3

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

@@ -0,0 +1,196 @@
+#!/usr/bin/env sh
+# Plane ticket-provider adapter.
+#
+# Credentials:  PLANE_API_KEY   (X-API-Key header)
+# Endpoint:     PLANE_BASE       (default https://plane.delo.sh)
+# Board binding (role.yaml `ticket_provider:`):
+#   name: plane
+#   workspace: <workspace-slug>      (or env PLANE_WORKSPACE)
+#   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
+#   backlog|unstarted|started|completed|cancelled.
+#
+# NOTE: REST paths follow Plane's v1 public API. Verify against a live board on
+# first use; state/cycle naming varies per workspace.
+set -eu
+
+OP="${1:-}"; shift 2>/dev/null || true
+ROLE_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
+ROLE_YAML="$ROLE_DIR/role.yaml"
+BASE="${PLANE_BASE:-https://plane.delo.sh}"
+
+die() { echo "plane: $*" >&2; exit 1; }
+need_key() { [ -n "${PLANE_API_KEY:-}" ] || die "PLANE_API_KEY is not set"; }
+
+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 ""
+mm = re.search(rf'(?m)^\s*{re.escape(sys.argv[2])}:\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. This is preferred over role.yaml so all of
+# a repo's agents resolve to the same board.
+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
+}
+
+# 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)"
+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"
+
+# api METHOD PATH [JSON_BODY] — call Plane REST, print response body.
+api() {
+  need_key
+  method="$1"; path="$2"; body="${3:-}"
+  if [ -n "$body" ]; then
+    curl -fsS -X "$method" "$API/$path" \
+      -H "X-API-Key: $PLANE_API_KEY" -H "Content-Type: application/json" \
+      -d "$body"
+  else
+    curl -fsS -X "$method" "$API/$path" -H "X-API-Key: $PLANE_API_KEY"
+  fi
+}
+
+# Map a normalized state -> a concrete Plane state id in this project.
+resolve_state_id() {
+  want="$1"
+  [ -n "$PROJ" ] || die "ticket_provider.project not set"
+  case "$want" in
+    completed) grp=completed; nm="$SM_DONE" ;;
+    in_review) grp=started;   nm="$SM_IN_REVIEW" ;;
+    started)   grp=started;   nm="" ;;
+    unstarted) grp=unstarted; nm="" ;;
+    backlog)   grp=backlog;   nm="" ;;
+    *) die "invalid normalized state: $want" ;;
+  esac
+  api GET "projects/$PROJ/states/" | GRP="$grp" NM="$nm" python3 -c 'import sys,json,os
+d=json.load(sys.stdin); rows=d.get("results", d if isinstance(d,list) else [])
+grp=os.environ["GRP"]; nm=os.environ.get("NM","")
+named=[s for s in rows if nm and (s.get("name","").lower()==nm.lower())]
+grouped=[s for s in rows if s.get("group")==grp]
+pick=(named or grouped or [{}])[0]
+print(pick.get("id",""))'
+}
+
+# All Plane ops require the API key; fail fast and clean before any pipe.
+need_key
+
+case "$OP" in
+  resolve)
+    [ -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"
+    ;;
+
+  active_milestone)
+    [ -n "$PROJ" ] || die "project not set"
+    api GET "projects/$PROJ/cycles/" | python3 -c 'import sys,json,datetime
+d=json.load(sys.stdin); rows=d.get("results", d if isinstance(d,list) else [])
+now=datetime.datetime.now(datetime.timezone.utc)
+def cur(c):
+    s,e=c.get("start_date"),c.get("end_date")
+    return bool(s and e and s<=now.date().isoformat()<=e)
+active=[c for c in rows if cur(c)] or rows
+m=active[0] if active else {}
+print(json.dumps({"id":m.get("id",""),"name":m.get("name",""),"state":"active" if active else ""}))'
+    ;;
+
+  list_issues)
+    [ -n "$PROJ" ] || die "project not set"
+    # Plane v1 returns issue.state as a bare UUID, so join against the states map.
+    STATES="$(api GET "projects/$PROJ/states/")"
+    ISSUES="$(api GET "projects/$PROJ/issues/")"
+    printf '%s\n%s\n' "$STATES" "$ISSUES" | BASE="$BASE" WS="$WS" PROJ="$PROJ" python3 -c 'import sys,json,os
+parts=sys.stdin.read().split("\n",1)
+srows=json.loads(parts[0] or "{}"); srows=srows.get("results", srows if isinstance(srows,list) else [])
+smap={s.get("id"):(s.get("name",""),s.get("group","")) for s in srows}
+d=json.loads(parts[1] or "{}"); rows=d.get("results", d if isinstance(d,list) else [])
+base,ws,proj=os.environ["BASE"],os.environ["WS"],os.environ["PROJ"]
+out=[]
+for n in rows:
+    iid=n.get("id","")
+    name,group=smap.get(n.get("state",""),("",""))
+    out.append({"id":iid,"key":n.get("sequence_id",iid),
+                "title":n.get("name",""),"state":name,"state_type":group,
+                "updated_at":n.get("updated_at",""),"assignee":"",
+                "url":base+"/"+ws+"/projects/"+proj+"/issues/"+str(iid)})
+print(json.dumps(out))'
+    ;;
+
+  get_issue)
+    ID="${1:?usage: get_issue <id>}"
+    STATES="$(api GET "projects/$PROJ/states/")"
+    ISSUE="$(api GET "projects/$PROJ/issues/$ID/")"
+    COMM="$(api GET "projects/$PROJ/issues/$ID/comments/" 2>/dev/null || echo '[]')"
+    printf '%s\n%s\n%s\n' "$STATES" "$ISSUE" "$COMM" | python3 -c 'import sys,json,re
+parts=sys.stdin.read().split("\n",2)
+srows=json.loads(parts[0] or "{}"); srows=srows.get("results", srows if isinstance(srows,list) else [])
+smap={s.get("id"):(s.get("name",""),s.get("group","")) for s in srows}
+i=json.loads(parts[1] or "{}"); c=json.loads(parts[2] or "[]")
+rows=c.get("results", c if isinstance(c,list) else [])
+def strip(h): return re.sub(r"<[^>]+>","",h or "").strip()
+name,group=smap.get(i.get("state",""),("",""))
+desc=strip(i.get("description_html",""))
+cs=[{"id":x.get("id",""),"body":strip(x.get("comment_html","")),"author":""} for x in rows]
+print(json.dumps({"id":i.get("id",""),"key":i.get("sequence_id",""),"title":i.get("name",""),
+                  "description":desc,"acceptance":desc,
+                  "state":name,"state_type":group,"comments":cs}))'
+    ;;
+
+  comment)
+    ID="${1:?usage: comment <id> <body>}"; BODY="${2:?}"
+    api POST "projects/$PROJ/issues/$ID/comments/" \
+      "$(python3 -c 'import json,sys; print(json.dumps({"comment_html":"<p>"+sys.argv[1]+"</p>"}))' "$BODY")" \
+      | python3 -c 'import sys,json; print(json.load(sys.stdin).get("id",""))'
+    ;;
+
+  transition)
+    ID="${1:?usage: transition <id> <normalized-state>}"; TARGET="${2:?}"
+    SID="$(resolve_state_id "$TARGET")"
+    [ -n "$SID" ] || die "no Plane state for normalized '$TARGET'"
+    api PATCH "projects/$PROJ/issues/$ID/" "$(printf '{"state":"%s"}' "$SID")" \
+      | python3 -c 'import sys,json; d=json.load(sys.stdin); print("ok "+str(d.get("sequence_id","")) )'
+    ;;
+
+  create_board)
+    NAME="${1:?usage: create_board <name> <ident> <desc>}"; IDENT="${2:-}"; DESC="${3:-}"
+    [ -n "$WS" ] || die "workspace not set"
+    EXIST="$(api GET "projects/?per_page=200" | IDENT="$IDENT" python3 -c 'import sys,json,os
+d=json.load(sys.stdin); rows=d.get("results", d if isinstance(d,list) else [])
+ident=os.environ["IDENT"].upper()
+print(next((p["id"] for p in rows if (p.get("identifier") or "").upper()==ident), ""))')"
+    if [ -n "$EXIST" ]; then PID="$EXIST"; else
+      PID="$(api POST "projects/" \
+        "$(python3 -c 'import json,sys; print(json.dumps({"name":sys.argv[1],"identifier":sys.argv[2],"description":sys.argv[3]}))' "$NAME" "$IDENT" "$DESC")" \
+        | python3 -c 'import sys,json; print(json.load(sys.stdin).get("id",""))')"
+    fi
+    [ -n "$PID" ] || die "create_board failed"
+    printf '{"board_id":"%s","board_url":"%s/%s/projects/%s/issues/"}\n' "$PID" "$BASE" "$WS" "$PID"
+    ;;
+
+  *) die "unknown op: $OP" ;;
+esac

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

@@ -0,0 +1,160 @@
+#!/usr/bin/env sh
+# Trello ticket-provider adapter.
+#
+# Credentials:  TRELLO_KEY  TRELLO_TOKEN   (query-param auth)
+# Board binding (role.yaml `ticket_provider:`):
+#   name: trello
+#   board: <board-id>                 (set by create_board / 42-ticket-provider)
+#   state_map: { backlog:"Backlog", unstarted:"To Do", started:"In Progress",
+#                in_review:"Review", completed:"Done" }   optional
+#
+# Trello model:  board = project & milestone, list = state, card = issue.
+# Trello has no milestone primitive, so active_milestone returns the board.
+#
+# NOTE: list names are matched case-insensitively against state_map; override
+# state_map in role.yaml if the board uses different column names.
+set -eu
+
+OP="${1:-}"; shift 2>/dev/null || true
+ROLE_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
+ROLE_YAML="$ROLE_DIR/role.yaml"
+API="https://api.trello.com/1"
+
+die() { echo "trello: $*" >&2; exit 1; }
+need_key() { [ -n "${TRELLO_KEY:-}" ] && [ -n "${TRELLO_TOKEN:-}" ] || die "TRELLO_KEY and TRELLO_TOKEN must be set"; }
+
+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 ""
+mm = re.search(rf'(?m)^\s*{re.escape(sys.argv[2])}:\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
+}
+
+BOARD="$(pj_cfg board_id)"; [ -n "$BOARD" ] || BOARD="$(tp_cfg board)"
+# Normalized -> Trello list name (overridable via role.yaml state_map keys).
+list_name_for() {
+  case "$1" in
+    backlog)   v="$(tp_cfg backlog)";   printf '%s' "${v:-Backlog}" ;;
+    unstarted) v="$(tp_cfg unstarted)"; printf '%s' "${v:-To Do}" ;;
+    started)   v="$(tp_cfg started)";   printf '%s' "${v:-In Progress}" ;;
+    in_review) v="$(tp_cfg in_review)"; printf '%s' "${v:-Review}" ;;
+    completed) v="$(tp_cfg completed)"; printf '%s' "${v:-Done}" ;;
+    *) die "invalid normalized state: $1" ;;
+  esac
+}
+
+# api METHOD PATH [extra-query] — call Trello, auth appended, print body.
+api() {
+  need_key
+  method="$1"; path="$2"; extra="${3:-}"
+  sep="?"; case "$path" in *\?*) sep="&" ;; esac
+  url="$API/$path${sep}key=$TRELLO_KEY&token=$TRELLO_TOKEN${extra:+&$extra}"
+  curl -fsS -X "$method" "$url"
+}
+
+# Resolve a list id on the board by (normalized) state.
+list_id_for() {
+  [ -n "$BOARD" ] || die "ticket_provider.board not set"
+  want="$(list_name_for "$1")"
+  api GET "boards/$BOARD/lists" | NM="$want" python3 -c 'import sys,json,os
+rows=json.load(sys.stdin); nm=os.environ["NM"].lower()
+print(next((l["id"] for l in rows if l.get("name","").lower()==nm), ""))'
+}
+
+# All Trello ops require credentials; fail fast and clean before any pipe.
+need_key
+
+case "$OP" in
+  resolve)
+    [ -n "$BOARD" ] || die "board not set (run 42-ticket-provider.sh)"
+    api GET "boards/$BOARD" "fields=name,url" | python3 -c 'import sys,json
+b=json.load(sys.stdin); print(json.dumps({"provider":"trello","board_id":b.get("id",""),"board_url":b.get("url","")}))'
+    ;;
+
+  active_milestone)
+    [ -n "$BOARD" ] || die "board not set"
+    api GET "boards/$BOARD" "fields=name" | python3 -c 'import sys,json
+b=json.load(sys.stdin); print(json.dumps({"id":b.get("id",""),"name":b.get("name",""),"state":"active"}))'
+    ;;
+
+  list_issues)
+    [ -n "$BOARD" ] || die "board not set"
+    # cards + lists, then label each card with its list name as the state.
+    LISTS="$(api GET "boards/$BOARD/lists" "fields=name")"
+    CARDS="$(api GET "boards/$BOARD/cards" "fields=name,idList,dateLastActivity,url,shortLink")"
+    printf '%s\n%s\n' "$LISTS" "$CARDS" | python3 -c 'import sys,json
+parts=sys.stdin.read().split("\n",1)
+lists={l["id"]:l.get("name","") for l in json.loads(parts[0] or "[]")}
+out=[]
+for c in json.loads(parts[1] or "[]"):
+    nm=lists.get(c.get("idList",""),"")
+    out.append({"id":c.get("id",""),"key":c.get("shortLink",""),"title":c.get("name",""),
+                "state":nm,"state_type":nm.lower().replace(" ","_"),
+                "updated_at":c.get("dateLastActivity",""),"assignee":"","url":c.get("url","")})
+print(json.dumps(out))'
+    ;;
+
+  get_issue)
+    ID="${1:?usage: get_issue <id>}"
+    CARD="$(api GET "cards/$ID" "fields=name,desc,idList")"
+    COMM="$(api GET "cards/$ID/actions" "filter=commentCard")"
+    printf '%s\n%s\n' "$CARD" "$COMM" | python3 -c 'import sys,json
+parts=sys.stdin.read().split("\n",1)
+c=json.loads(parts[0] or "{}"); acts=json.loads(parts[1] or "[]")
+cs=[{"id":a.get("id",""),"body":(a.get("data") or {}).get("text",""),"author":(a.get("memberCreator") or {}).get("fullName","")} for a in acts]
+print(json.dumps({"id":c.get("id",""),"key":c.get("id",""),"title":c.get("name",""),
+                  "description":c.get("desc",""),"acceptance":c.get("desc",""),
+                  "state":"","state_type":"","comments":cs}))'
+    ;;
+
+  comment)
+    ID="${1:?usage: comment <id> <body>}"; BODY="${2:?}"
+    api POST "cards/$ID/actions/comments" "text=$(python3 -c 'import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))' "$BODY")" \
+      | python3 -c 'import sys,json; print(json.load(sys.stdin).get("id",""))'
+    ;;
+
+  transition)
+    ID="${1:?usage: transition <id> <normalized-state>}"; TARGET="${2:?}"
+    LID="$(list_id_for "$TARGET")"
+    [ -n "$LID" ] || die "no Trello list mapped for normalized '$TARGET' (check state_map)"
+    api PUT "cards/$ID" "idList=$LID" | python3 -c 'import sys,json; c=json.load(sys.stdin); print("ok "+c.get("id",""))'
+    ;;
+
+  create_board)
+    NAME="${1:?usage: create_board <name> <ident> <desc>}"
+    EXIST="$(api GET "members/me/boards" "fields=name" | NM="$NAME" python3 -c 'import sys,json,os
+rows=json.load(sys.stdin); nm=os.environ["NM"].lower()
+print(next((b["id"] for b in rows if b.get("name","").lower()==nm), ""))')"
+    if [ -n "$EXIST" ]; then BID="$EXIST"; else
+      BID="$(api POST "boards/" "name=$(python3 -c 'import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))' "$NAME")&defaultLists=true" \
+        | python3 -c 'import sys,json; print(json.load(sys.stdin).get("id",""))')"
+    fi
+    [ -n "$BID" ] || die "create_board failed"
+    api GET "boards/$BID" "fields=url" | BID="$BID" python3 -c 'import sys,json,os
+b=json.load(sys.stdin); print(json.dumps({"board_id":os.environ["BID"],"board_url":b.get("url","")}))'
+    ;;
+
+  *) die "unknown op: $OP" ;;
+esac

package/templates/hermes-agent/template/.scripts/scrum-master/bin/emit-event.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""Emit a local BloodBank-style CloudEvents envelope (provider-agnostic).
+
+Dependency-free. Appends JSONL locally so the Scrum Master engine records an
+event trail even when NATS/BloodBank is offline. Identical envelope shape to the
+Hermes gateway; see .scripts/scrum-master/docs/bloodbank-events.md.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import pathlib
+import sys
+import uuid
+from datetime import datetime, timezone
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def parse_field(raw: str) -> tuple[str, str]:
+    if "=" not in raw:
+        raise argparse.ArgumentTypeError("--field values must use key=value")
+    key, value = raw.split("=", 1)
+    if not key:
+        raise argparse.ArgumentTypeError("--field key cannot be empty")
+    return key, value
+
+
+def load_data(args: argparse.Namespace) -> dict:
+    data: dict[str, object] = {}
+    for key, value in args.field or []:
+        data[key] = value
+    if args.data_json:
+        loaded = json.loads(args.data_json)
+        if not isinstance(loaded, dict):
+            raise SystemExit("--data-json must be a JSON object")
+        data.update(loaded)
+    elif not sys.stdin.isatty():
+        raw = sys.stdin.read().strip()
+        if raw:
+            loaded = json.loads(raw)
+            if not isinstance(loaded, dict):
+                raise SystemExit("stdin JSON must be an object")
+            data.update(loaded)
+    return data
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("event_type")
+    parser.add_argument("--root", default=os.getcwd())
+    parser.add_argument("--field", action="append", type=parse_field, default=[])
+    parser.add_argument("--data-json")
+    parser.add_argument("--source")
+    parser.add_argument("--producer", default=os.environ.get("BLOODBANK_PRODUCER", "local-script:scrum-master"))
+    parser.add_argument("--service", default=os.environ.get("BLOODBANK_SERVICE", "hermes-scrum-master"))
+    parser.add_argument("--actor-id", default=os.environ.get("BLOODBANK_ACTOR_ID", os.environ.get("USER", "local-agent")))
+    parser.add_argument("--actor-cli", default=os.environ.get("BLOODBANK_ACTOR_CLI", "script"))
+    parser.add_argument("--correlation-id", default=os.environ.get("BLOODBANK_CORRELATION_ID"))
+    parser.add_argument("--causation-id", default=os.environ.get("BLOODBANK_CAUSATION_ID"))
+    parser.add_argument("--kind", default="event")
+    parser.add_argument("--quiet", action="store_true")
+    args = parser.parse_args()
+
+    root = pathlib.Path(args.root).resolve()
+    log_path = pathlib.Path(
+        os.environ.get(
+            "BLOODBANK_EVENTS_LOG",
+            root / "_bmad-output" / "implementation-artifacts" / "bloodbank-events.jsonl",
+        )
+    )
+    if not log_path.is_absolute():
+        log_path = root / log_path
+
+    source = args.source or "repo://scrum-master/bin/emit-event.py"
+    event = {
+        "specversion": "1.0",
+        "type": args.event_type,
+        "id": str(uuid.uuid4()),
+        "source": source,
+        "time": now_iso(),
+        "datacontenttype": "application/json",
+        "kind": args.kind,
+        "producer": args.producer,
+        "service": args.service,
+        "actor": {"type": "agent", "agent_id": args.actor_id, "cli": args.actor_cli},
+        "data": load_data(args),
+        "correlation_id": args.correlation_id or str(uuid.uuid4()),
+        "causation_id": args.causation_id,
+    }
+
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+    with log_path.open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps(event, sort_keys=True) + "\n")
+
+    if not args.quiet:
+        print(json.dumps(event, indent=2, sort_keys=True))
+        print(f"Appended: {log_path}", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())