@delorenj/pjangler 1.1.3

package/templates/hermes-agent/template/.scripts/75-scrum-master.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+# Install the Scrum Master continuous-ticket sentinel: systemd timer + runner,
+# and stage the engine docs + enforcement tools into the role dir.
+# Only meaningful for role: scrum-master (copier guards the _tasks call).
+# shellcheck source=_lib.sh
+source "$(dirname "$0")/_lib.sh"
+load_role_env
+
+if [[ "$ROLE" != "scrum-master" ]]; then
+  log "[75] role is '$ROLE', not scrum-master — skipping sentinel install"; exit 0
+fi
+if already_done 75-scrum-master && [[ "${FORCE_SENTINEL:-0}" != "1" ]]; then
+  log "[75] scrum master sentinel already installed — skipping"; exit 0
+fi
+
+RUNTIME="$ROLE_DIR/runtime"
+PROFILE_HOME="$(profile_or_runtime_home)"
+REPO_ROOT="$(project_repo_path)"
+RUNNER="$ROLE_DIR/.scripts/scrum-master/continuous-ticket-sentinel.sh"
+SYS_DIR="$HOME/.config/systemd/user"
+mkdir -p "$SYS_DIR" "$PROFILE_HOME/logs"
+
+[[ -f "$RUNNER" ]] || die "[75] runner missing: $RUNNER (template render incomplete)"
+chmod +x "$RUNNER" "$ROLE_DIR/.scripts/scrum-master/"*.sh 2>/dev/null || true
+chmod +x "$ROLE_DIR/.scripts/scrum-master/bin/"*.sh 2>/dev/null || true
+
+LOG="$PROFILE_HOME/logs/continuous-ticket-sentinel.log"
+ENV_FILE="$HOME/.hermes/${AGENT_ID}.env"
+
+if [[ "$(uname -s)" == "Darwin" ]]; then
+  # macOS: a launchd LaunchAgent that runs the sentinel every 60 seconds. It
+  # sources the per-agent env file (ticket-provider keys) and exports them.
+  LA_DIR="$HOME/Library/LaunchAgents"
+  mkdir -p "$LA_DIR"
+  LABEL="com.hermes.${AGENT_ID}.sentinel"
+  PLIST="$LA_DIR/$LABEL.plist"
+  cat > "$PLIST" <<PLIST
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>$LABEL</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/sh</string>
+    <string>-lc</string>
+    <string>set -a; [ -f "$ENV_FILE" ] &amp;&amp; . "$ENV_FILE"; set +a; exec "$RUNNER"</string>
+  </array>
+  <key>StartInterval</key><integer>60</integer>
+  <key>RunAtLoad</key><true/>
+  <key>WorkingDirectory</key><string>$REPO_ROOT</string>
+  <key>EnvironmentVariables</key>
+  <dict><key>HERMES_HOME</key><string>$PROFILE_HOME</string></dict>
+  <key>StandardOutPath</key><string>$LOG</string>
+  <key>StandardErrorPath</key><string>$LOG</string>
+</dict>
+</plist>
+PLIST
+  launchctl unload "$PLIST" >/dev/null 2>&1 || true
+  if launchctl load -w "$PLIST" >/dev/null 2>&1; then
+    log "    loaded launchd agent: $LABEL"
+  else
+    warn "    launchd load failed; plist written at $PLIST"
+  fi
+else
+  # Linux: systemd --user oneshot service plus a 1-minute timer.
+  ENV_FILES="$(cat <<'ENVFILES'
+EnvironmentFile=-%h/.config/hermes-agent/env
+EnvironmentFile=-%h/.hermes/env
+EnvironmentFile=-%h/.hermes/hermes-agent.env
+ENVFILES
+)"
+  ENV_FILES="$ENV_FILES
+EnvironmentFile=-%h/.hermes/${AGENT_ID}.env"
+  SVC_UNIT="hermes-${AGENT_ID}-continuous-ticket-sentinel.service"
+  TIMER_UNIT="hermes-${AGENT_ID}-continuous-ticket-sentinel.timer"
+  cat > "$SYS_DIR/$SVC_UNIT" <<UNIT
+[Unit]
+Description=Hermes Continuous Ticket Sentinel — $DISPLAY_NAME
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+WorkingDirectory=$REPO_ROOT
+Environment=HERMES_HOME=$PROFILE_HOME
+$ENV_FILES
+ExecStart=$RUNNER
+TimeoutStartSec=45min
+StandardOutput=append:$LOG
+StandardError=append:$LOG
+UNIT
+  cat > "$SYS_DIR/$TIMER_UNIT" <<UNIT
+[Unit]
+Description=Continuous ticket sentinel for $AGENT_ID
+
+[Timer]
+OnBootSec=1min
+OnUnitInactiveSec=1min
+Unit=$SVC_UNIT
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+UNIT
+  if systemd_user_available; then
+    systemctl --user daemon-reload
+    systemctl --user enable --now "$TIMER_UNIT" >/dev/null 2>&1 \
+      && log "    enabled: $TIMER_UNIT" \
+      || warn "    failed to enable: $TIMER_UNIT"
+  else
+    warn "    systemd --user not available; units installed at $SYS_DIR but not enabled"
+  fi
+fi
+
+log "[75] scrum master sentinel installed (provider: $(yaml_get ticket_provider.name))"
+mark_done 75-scrum-master

package/templates/hermes-agent/template/.scripts/80-registry.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# Append this agent's entry to the global fleet registry.
+# shellcheck source=_lib.sh
+source "$(dirname "$0")/_lib.sh"
+load_role_env
+
+mkdir -p "$(dirname "$REGISTRY_FILE")"
+if [[ ! -f "$REGISTRY_FILE" ]]; then
+  cat > "$REGISTRY_FILE" <<'YAML'
+# Hermes agent fleet registry.
+# One entry per provisioned agent. Managed by hermes-agent-template/.scripts/80-registry.sh.
+schema_version: 1
+agents: {}
+YAML
+fi
+
+PROJECT_PATH="$(project_repo_path)" || PROJECT_PATH=""
+PLANE_PROJECT_ID="$(cat "$ROLE_DIR/.scripts/.plane-project-id" 2>/dev/null || true)"
+
+log "[80] appending to fleet registry: $REGISTRY_FILE"
+
+python3 - "$REGISTRY_FILE" "$AGENT_ID" "$REPO" "$ROLE" "$DISPLAY_NAME" \
+  "$PROJECT_PATH" "$ROLE_DIR" "$PROFILE_NAME" \
+  "$BOT_HANDLE" \
+  "$PLANE_WORKSPACE" "$PLANE_PROJECT_ID" "$(yaml_get plane.identifier)" \
+  "$RUNTIME_REPO" "$HERMES_BIN" "$HERMES_AGENT_REPO" "$FLEET_ENV" \
+  "hermes-${AGENT_ID}-gateway.service" "hermes-${AGENT_ID}-consumer.service" \
+  "hermes-${AGENT_ID}-checkpoint.timer" <<'PYEOF'
+import sys, pathlib, datetime
+try:
+    import yaml  # type: ignore
+except ImportError:
+    sys.exit("PyYAML required; pip install pyyaml")
+(path, agent_id, repo, role, display, project, role_dir, profile, bot,
+ plane_ws, plane_id, plane_ident, runtime_repo, hermes_bin, hermes_repo,
+ fleet_env, gw, csm, ckpt) = sys.argv[1:20]
+p = pathlib.Path(path)
+data = yaml.safe_load(p.read_text()) or {"schema_version": 1, "agents": {}}
+data.setdefault("agents", {})[agent_id] = {
+  "repo": repo, "role": role, "display_name": display,
+  "project_path": project, "role_dir": role_dir,
+  "profile_name": profile,
+  "telegram": {"bot_username": bot},
+  "plane": {"workspace": plane_ws, "project_id": plane_id, "identifier": plane_ident},
+  "runtime_repo": runtime_repo,
+  "hermes": {"bin": hermes_bin, "repo": hermes_repo, "fleet_env": fleet_env},
+  "systemd": {"gateway_unit": gw, "consumer_unit": csm, "checkpoint_timer": ckpt},
+  "provisioned_at": datetime.datetime.utcnow().isoformat() + "Z",
+}
+p.write_text(yaml.safe_dump(data, sort_keys=False))
+PYEOF
+
+mark_done 80-registry

package/templates/hermes-agent/template/.scripts/90-chain-scrum-master.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# When a PM is provisioned with with_scrum_master=yes, chain a paired Scrum
+# Master provision for the same repo + ticket provider into a sibling role dir.
+# Idempotent: skips if agents/hermes/scrum-master already exists.
+# shellcheck source=_lib.sh
+source "$(dirname "$0")/_lib.sh"
+load_role_env
+
+already_done 90-chain-scrum-master && { log "[90] scrum master already chained — skipping"; exit 0; }
+
+# Sibling path: .../agents/hermes/scrum-master  (peer of this pm role dir).
+HERMES_DIR="$(dirname "$ROLE_DIR")"
+SM_DIR="$HERMES_DIR/scrum-master"
+
+if [[ -d "$SM_DIR" ]]; then
+  log "[90] $SM_DIR already exists — not re-provisioning"; mark_done 90-chain-scrum-master; exit 0
+fi
+
+# Resolve the template source from this provision's copier answers.
+ANSWERS="$ROLE_DIR/.copier-answers.yml"
+SRC="$(yaml_get _src_path 2>/dev/null || true)"
+[[ -z "$SRC" && -f "$ANSWERS" ]] && SRC="$(python3 -c 'import sys,re,pathlib;
+t=pathlib.Path(sys.argv[1]).read_text();m=re.search(r"(?m)^_src_path:\s*(.+)$",t);print((m.group(1).strip() if m else ""))' "$ANSWERS")"
+SRC="${SRC:-gh:delorenj/hermes-agent-template}"
+
+PROVIDER="$(yaml_get ticket_provider.name)"; PROVIDER="${PROVIDER:-plane}"
+
+if ! command -v copier >/dev/null 2>&1; then
+  warn "[90] copier not on PATH; provision the Scrum Master manually:"
+  warn "     copier copy --trust $SRC $SM_DIR --data role=scrum-master --data target_repo=$REPO --data ticket_provider=$PROVIDER"
+  mark_done 90-chain-scrum-master; exit 0
+fi
+
+log "[90] chaining Scrum Master provision -> $SM_DIR (provider: $PROVIDER)"
+# --trust is REQUIRED: the hermes-agent template uses copier `tasks`, which copier
+# refuses to run unless explicitly trusted. Without it the chained provision aborts
+# with "Template uses potentially unsafe feature: tasks" and the SM is never created.
+copier copy --defaults --overwrite --trust \
+  --data role=scrum-master \
+  --data target_repo="$REPO" \
+  --data ticket_provider="$PROVIDER" \
+  "$SRC" "$SM_DIR" \
+  || warn "[90] chained scrum-master provision failed; run it manually (see command above)"
+
+mark_done 90-chain-scrum-master

package/templates/hermes-agent/template/.scripts/99-summary.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Print the final summary and next steps.
+# shellcheck source=_lib.sh
+source "$(dirname "$0")/_lib.sh"
+load_role_env
+
+GW_UNIT="hermes-${AGENT_ID}-gateway.service"
+CSM_UNIT="hermes-${AGENT_ID}-consumer.service"
+CKPT_TIMER="hermes-${AGENT_ID}-checkpoint.timer"
+
+cat >&2 <<EOF
+
+╭─ Provisioned: $AGENT_ID ───────────────────────────────────────────────╮
+│
+│  Talk:        @$BOT_HANDLE  (Telegram DM)
+│  Shell:       $ROLE_DIR/hermes chat "status"
+│  Profile:     $PROFILE_NAME  (config inherits from default; secrets stay local)
+│  Board:       $PLANE_BASE/$PLANE_WORKSPACE/projects/$(cat "$ROLE_DIR/.scripts/.plane-project-id" 2>/dev/null || echo "(skipped)")
+│  Runtime:     gh:$RUNTIME_REPO   (auto-checkpointed hourly)
+│  Hermes bin:  $HERMES_BIN
+│  Fleet env:   $FLEET_ENV
+│
+│  Start fleet daemons:
+│    systemctl --user start $GW_UNIT
+│    systemctl --user start $CSM_UNIT
+│    systemctl --user start $CKPT_TIMER
+│
+│  Tail logs:
+│    journalctl --user -fu $GW_UNIT
+│    journalctl --user -fu $CSM_UNIT
+│
+│  Fleet status:
+│    python3 -c "import yaml,pathlib; print(yaml.safe_dump(yaml.safe_load(pathlib.Path('$REGISTRY_FILE').read_text())['agents']))"
+│
+╰────────────────────────────────────────────────────────────────────────╯
+
+EOF
+mark_done 99-summary

package/templates/hermes-agent/template/.scripts/_lib.sh

@@ -0,0 +1,208 @@
+# shellcheck shell=bash
+# Common helpers sourced by every numbered provisioning step.
+
+set -euo pipefail
+
+# These three are set by Copier into the rendered role.yaml; we re-derive them
+# here so each script is callable in isolation (e.g. for repair runs).
+ROLE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+ROLE_YAML="$ROLE_DIR/role.yaml"
+PROV_LOG="$ROLE_DIR/.scripts/.provision.log"
+
+mkdir -p "$ROLE_DIR/.scripts"
+
+# Logging
+log()  { local msg="[$(date +%H:%M:%S)] $*"; printf '\033[36m%s\033[0m\n' "$msg" >&2; printf '%s\n' "$msg" >> "$PROV_LOG"; }
+warn() { local msg="[$(date +%H:%M:%S)] $*"; printf '\033[33m%s\033[0m\n' "$msg" >&2; printf '%s\n' "$msg" >> "$PROV_LOG"; }
+err()  { local msg="[$(date +%H:%M:%S)] $*"; printf '\033[31m%s\033[0m\n' "$msg" >&2; printf '%s\n' "$msg" >> "$PROV_LOG"; }
+die()  { err "$*"; exit 1; }
+
+# Read a single field from role.yaml. Requires python3 (no yaml dep).
+yaml_get() {
+  # yaml_get  KEY[.SUBKEY]    e.g.  yaml_get role,  yaml_get telegram.bot_username
+  local key="$1"
+  python3 - "$ROLE_YAML" "$key" <<'PYEOF'
+import sys, re, pathlib
+path, key = sys.argv[1:3]
+text = pathlib.Path(path).read_text()
+parts = key.split(".")
+# Trivial YAML walker — handles flat and one-level nested keys.
+indent = -1
+prefix = ""
+for part in parts[:-1]:
+    indent += 2
+    prefix += part + ":"
+    m = re.search(rf"(?m)^{re.escape(part)}:\s*$", text)
+    if not m:
+        sys.exit(0)
+    text = text[m.end():]
+key = parts[-1]
+m = re.search(rf'(?m)^\s*{re.escape(key)}:\s*"?([^"\n]*)"?\s*$', text)
+if m:
+    print(m.group(1).strip())
+PYEOF
+}
+
+# Apply a sed substitution to role.yaml in-place. Used to record IDs after
+# external provisioning steps return them.
+yaml_set() {
+  # yaml_set KEY VALUE   (only updates the first match; key must already exist)
+  local key="$1" val="$2"
+  python3 - "$ROLE_YAML" "$key" "$val" <<'PYEOF'
+import sys, re, pathlib
+path, key, val = sys.argv[1:4]
+p = pathlib.Path(path); text = p.read_text()
+# Match `<indent><key>:<...>` and rewrite the value (last leaf only).
+leaf = key.split(".")[-1]
+new = re.sub(rf'(?m)^(\s*{re.escape(leaf)}:\s*)("?)[^"\n]*("?)\s*$',
+             lambda m: f'{m.group(1)}"{val}"', text, count=1)
+if new == text:
+    sys.exit(f"yaml_set: leaf '{leaf}' not found in {path}")
+p.write_text(new)
+PYEOF
+}
+
+# ─── Distributable config (~/.config/hermes-agent-template/config.toml) ──────
+# Single source of truth for environment-specific defaults so this template can
+# be handed to someone else without editing any script. Ship config.example.toml
+# is copied here on first provision (see .scripts/01-config.sh).
+HERMES_TEMPLATE_CONFIG="${HERMES_TEMPLATE_CONFIG:-${XDG_CONFIG_HOME:-$HOME/.config}/hermes-agent-template/config.toml}"
+export HERMES_TEMPLATE_CONFIG
+
+# config_get <dotted.key> [default]   — print a value from config.toml (paths are
+# tilde-expanded; arrays are space-joined). Falls back to [default] when the file,
+# python3, or the key is missing. Always exits 0 so it's safe under `set -e`.
+config_get() {
+  local key="$1" def="${2:-}"
+  if [[ ! -f "$HERMES_TEMPLATE_CONFIG" ]] || ! command -v python3 >/dev/null 2>&1; then
+    printf '%s' "$def"; return 0
+  fi
+  python3 - "$HERMES_TEMPLATE_CONFIG" "$key" "$def" <<'PYEOF' || printf '%s' "$def"
+import sys, os
+try:
+    import tomllib
+except ModuleNotFoundError:  # python < 3.11
+    print(sys.argv[3], end=""); sys.exit(0)
+path, key, default = sys.argv[1], sys.argv[2], sys.argv[3]
+try:
+    with open(path, "rb") as f:
+        cur = tomllib.load(f)
+except Exception:
+    print(default, end=""); sys.exit(0)
+for part in key.split("."):
+    if isinstance(cur, dict) and part in cur:
+        cur = cur[part]
+    else:
+        print(default, end=""); sys.exit(0)
+if isinstance(cur, list):
+    cur = " ".join(str(x) for x in cur)
+else:
+    cur = str(cur)
+print(os.path.expanduser(cur), end="")
+PYEOF
+  return 0
+}
+
+# Re-export role fields into the environment for the rest of the script.
+load_role_env() {
+  ROLE=$(yaml_get role)
+  REPO=$(yaml_get repo)
+  AGENT_ID=$(yaml_get agent_id)
+  DISPLAY_NAME=$(yaml_get display_name)
+  BOT_HANDLE=$(yaml_get telegram.bot_username)
+  PROFILE_NAME=$(yaml_get profile)
+
+  # Plane workspace: empty in role.yaml -> resolve from config.toml.
+  PLANE_WORKSPACE=$(yaml_get plane.workspace)
+  [[ -n "$PLANE_WORKSPACE" ]] || PLANE_WORKSPACE=$(config_get plane.workspace "33god")
+
+  # Runtime repo: role.yaml stores the bare repo name plus an optional owner.
+  # Older manifests stored "owner/name" directly in github_repo; honor both.
+  RUNTIME_REPO=$(yaml_get runtime.github_repo)
+  if [[ "$RUNTIME_REPO" != */* ]]; then
+    local owner; owner=$(yaml_get runtime.github_owner)
+    [[ -n "$owner" ]] || owner=$(config_get github.runtime_repo_owner "delorenj")
+    RUNTIME_REPO="$owner/$RUNTIME_REPO"
+  fi
+
+  export ROLE REPO AGENT_ID DISPLAY_NAME BOT_HANDLE \
+         PLANE_WORKSPACE RUNTIME_REPO PROFILE_NAME
+}
+
+# Skip a step if previously completed (idempotent reruns).
+already_done() {
+  local marker="$ROLE_DIR/.scripts/.done-$1"
+  [[ -f "$marker" ]]
+}
+mark_done() {
+  touch "$ROLE_DIR/.scripts/.done-$1"
+}
+
+# Fleet source-of-truth (shared across all wrappers/provisioners).
+# Every default below resolves as: env var > fleet.env > config.toml > fallback.
+FLEET_ENV="${HERMES_FLEET_ENV:-$(config_get fleet.fleet_env "$HOME/.hermes/fleet.env")}"
+if [[ -f "$FLEET_ENV" ]]; then
+  # shellcheck disable=SC1090
+  source "$FLEET_ENV"
+fi
+
+# Tools we expect on the host
+HERMES_BIN="${HERMES_BIN:-${HERMES_FLEET_BIN:-$(config_get fleet.hermes_bin '/home/delorenj/code/hermes-agent/.venv/bin/hermes')}}"
+HERMES_AGENT_REPO="${HERMES_AGENT_REPO:-${HERMES_FLEET_REPO:-$(config_get fleet.hermes_repo '/home/delorenj/code/hermes-agent')}}"
+HERMES_OAUTH_FILE="${HERMES_OAUTH_FILE:-${HERMES_FLEET_OAUTH_FILE:-$(config_get fleet.oauth_file "$HOME/.hermes/auth.json")}}"
+CODEX_HOME="${CODEX_HOME:-${HERMES_FLEET_CODEX_HOME:-$(config_get fleet.codex_home "$HOME/.codex")}}"
+FLEET_HOME="${HERMES_FLEET_HOME:-$(config_get fleet.home "$HOME/.hermes")}"
+# Prefer a scaffold vendored into this agent directory; fall back to the configured template path.
+RUNTIME_SCAFFOLD_DIR="${RUNTIME_SCAFFOLD_DIR:-$ROLE_DIR/.runtime-scaffold}"
+if [[ ! -d "$RUNTIME_SCAFFOLD_DIR" ]]; then
+  RUNTIME_SCAFFOLD_DIR="${HERMES_TEMPLATE_RUNTIME_SCAFFOLD:-$(config_get fleet.runtime_scaffold_dir '/home/delorenj/code/hermes-agent-template/runtime-scaffold')}"
+fi
+REGISTRY_FILE="${REGISTRY_FILE:-${HERMES_FLEET_REGISTRY_FILE:-$(config_get fleet.registry_file "$HOME/.hermes/agents-registry.yaml")}}"
+
+# Bloodbank / NATS
+BLOODBANK_NATS_HOST="${BLOODBANK_NATS_HOST:-$(config_get bloodbank.nats_host '127.0.0.1')}"
+BLOODBANK_NATS_PORT="${BLOODBANK_NATS_PORT:-$(config_get bloodbank.nats_port '4222')}"
+BLOODBANK_COMPOSE_DIR="${BLOODBANK_COMPOSE_DIR:-$(config_get bloodbank.compose_dir "$HOME/code/33GOD/bloodbank")}"
+
+# Plane
+PLANE_BASE="${PLANE_BASE:-$(config_get plane.base 'https://plane.delo.sh')}"
+PLANE_API_KEY="${PLANE_API_KEY:-${PLANE_33GOD_API_KEY:-}}"
+
+export FLEET_ENV HERMES_BIN HERMES_AGENT_REPO HERMES_OAUTH_FILE CODEX_HOME FLEET_HOME \
+       RUNTIME_SCAFFOLD_DIR REGISTRY_FILE \
+       BLOODBANK_NATS_HOST BLOODBANK_NATS_PORT BLOODBANK_COMPOSE_DIR \
+       PLANE_BASE PLANE_API_KEY
+
+profile_home() {
+  printf '%s/profiles/%s' "$FLEET_HOME" "$PROFILE_NAME"
+}
+
+profile_or_runtime_home() {
+  local profile
+  profile="$(profile_home)"
+  if [[ -d "$profile" ]]; then
+    printf '%s' "$profile"
+  else
+    printf '%s/runtime' "$ROLE_DIR"
+  fi
+}
+
+# systemd --user health check. Accept running/degraded/starting — only one
+# broken unit shouldn't disqualify the rest of the user manager.
+systemd_user_available() {
+  command -v systemctl >/dev/null || return 1
+  local state; state=$(systemctl --user is-system-running 2>&1)
+  [[ "$state" =~ ^(running|degraded|starting|maintenance)$ ]]
+}
+
+# Resolve project repo path (the repo that holds agents/hermes/<role>/).
+# Walk up from $ROLE_DIR until we find a git root that isn't us.
+project_repo_path() {
+  local d="$ROLE_DIR"
+  [[ -d "$d/.git" || -f "$d/.git" ]] && { echo "$d"; return 0; }
+  for _ in 1 2 3 4 5; do
+    d="$(dirname "$d")"
+    [[ -d "$d/.git" || -f "$d/.git" ]] && { echo "$d"; return 0; }
+  done
+  return 1
+}

package/templates/hermes-agent/template/.scripts/checkpoint.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Auto-checkpoint commit for the agent's runtime submodule.
+# Idempotent — exits 0 with no commit if there are no changes.
+set -euo pipefail
+
+RUNTIME_DIR="$(cd "$(dirname "$0")/../runtime" && pwd)"
+cd "$RUNTIME_DIR"
+
+# Skip if not a git repo (e.g. submodule not initialized)
+[[ -d .git || -f .git ]] || exit 0
+
+git add -A
+if git diff --cached --quiet; then
+  exit 0
+fi
+git -c commit.gpgsign=false commit -m "checkpoint $(date -Iseconds)" >/dev/null
+git push origin HEAD 2>&1 | tail -1 || true

package/templates/hermes-agent/template/.scripts/config.example.toml

@@ -0,0 +1,55 @@
+# hermes-agent-template — distributable configuration
+#
+# This file holds every environment-specific default the provisioning scripts
+# need. Copy it to ~/.config/hermes-agent-template/config.toml (the first
+# provisioning run does this for you) and edit the values for YOUR machine.
+#
+# Resolution precedence for each value (highest wins):
+#   explicit env var  >  ~/.hermes/fleet.env  >  this file  >  built-in fallback
+#
+# Override the config location with $HERMES_TEMPLATE_CONFIG if you keep it
+# somewhere other than $XDG_CONFIG_HOME/hermes-agent-template/config.toml.
+
+[fleet]
+# Root Hermes fleet home. Named profiles live under <home>/profiles/<name>.
+home = "~/.hermes"
+# Absolute path to the shared Hermes executable every agent launcher execs.
+hermes_bin = "/home/delorenj/code/hermes-agent/.venv/bin/hermes"
+# Checkout of the hermes-agent repo. Its .venv is used to install nats-py, etc.
+hermes_repo = "/home/delorenj/code/hermes-agent"
+# Fallback runtime scaffold dir — used only when an agent's vendored
+# ./.runtime-scaffold is missing.
+runtime_scaffold_dir = "/home/delorenj/code/hermes-agent-template/runtime-scaffold"
+# Shared fleet source-of-truth env file + fleet registry. ~ is expanded.
+fleet_env = "~/.hermes/fleet.env"
+registry_file = "~/.hermes/agents-registry.yaml"
+# Shared auth roots. HERMES_OAUTH_FILE is the Hermes provider OAuth store
+# (including openai-codex); CODEX_HOME is for Codex CLI/app-server auth.
+oauth_file = "~/.hermes/auth.json"
+codex_home = "~/.codex"
+# Canonical external skills dir mirrored into each agent profile.
+canonical_skills_dir = "/home/delorenj/.agents/skills"
+# Skills symlinked into every agent's runtime skills root.
+symlinked_runtime_skills = [
+  "delonet-conventions",
+  "delonet-dotenv",
+  "hermes-pm-template-maintenance",
+  "hindsight",
+  "subagent-driven-development",
+]
+
+[github]
+# Owner of the per-agent runtime repos (creates <owner>/agent-hm-<repo>-<role>).
+runtime_repo_owner = "delorenj"
+
+[plane]
+# Plane instance base URL and workspace slug (one project per agent).
+base = "https://plane.delo.sh"
+workspace = "33god"
+
+[bloodbank]
+# NATS endpoint the consumer connects to.
+nats_host = "127.0.0.1"
+nats_port = 4222
+# Where the bloodbank docker compose lives (used only for a hint message). ~ ok.
+compose_dir = "~/code/33GOD/bloodbank"

package/templates/hermes-agent/template/.scripts/lib/ticket-provider.sh

@@ -0,0 +1,102 @@
+# shellcheck shell=bash
+# Ticket-provider adapter dispatcher — the single seam between the Scrum Master
+# sentinel engine and a concrete ticket system (Linear | Plane | Trello).
+#
+# The engine NEVER calls a provider directly. It calls `tp <op> [args...]`,
+# which dispatches to providers/<provider>.sh. Swapping providers is a one-line
+# config change in role.yaml (ticket_provider.name) — no engine edits.
+#
+# Contract (operations every provider must implement):
+#   resolve                       -> JSON {provider, board_id, board_url}
+#   active_milestone              -> JSON {id, name, state}
+#   list_issues                   -> JSON [ {id,key,title,state,state_type,
+#                                            updated_at,assignee,url}, ... ]
+#   get_issue <id>                -> JSON {id,key,title,description,acceptance,
+#                                          state,state_type,comments:[...]}
+#   comment <id> <body>           -> prints comment id
+#   transition <id> <normalized>  -> moves issue; normalized in
+#                                     backlog|unstarted|started|in_review|completed
+#   create_board <name> <id> <d>  -> JSON {board_id, board_url}
+#
+# Each provider reads its credentials from the environment (see providers/*.sh
+# headers) and the board binding from role.yaml under `ticket_provider:`.
+
+# Resolve the provider name: explicit env wins, then repo-root .project.json
+# (the SOT), then role.yaml (self-parsed so this works even when _lib.sh /
+# yaml_get is not loaded), then default.
+tp_provider_name() {
+  if [ -n "${TICKET_PROVIDER:-}" ]; then
+    printf '%s\n' "$TICKET_PROVIDER"
+    return 0
+  fi
+  # .project.json ticket_provider.type — walk up from the role dir to repo root.
+  local role_dir
+  role_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." 2>/dev/null && pwd)"
+  if [ -n "$role_dir" ]; then
+    local sot_type
+    sot_type="$(python3 - "$role_dir" <<'PY' 2>/dev/null
+import sys, json, pathlib
+start = pathlib.Path(sys.argv[1]).resolve()
+for parent in [start, *start.parents]:
+    f = parent / ".project.json"
+    if f.is_file():
+        try:
+            print((json.loads(f.read_text()).get("ticket_provider") or {}).get("type", ""))
+        except Exception:
+            print("")
+        break
+PY
+)"
+    [ -n "$sot_type" ] && { printf '%s\n' "$sot_type"; return 0; }
+  fi
+  local role_yaml
+  role_yaml="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." 2>/dev/null && pwd)/role.yaml"
+  if [ -f "$role_yaml" ]; then
+    local name
+    name="$(python3 - "$role_yaml" <<'PY'
+import re, sys, pathlib
+t = pathlib.Path(sys.argv[1]).read_text()
+m = re.search(r'(?ms)^ticket_provider:\s*$(.*?)(?=^\S)', t + "\n\x00")
+block = m.group(1) if m else ""
+mm = re.search(r'(?m)^\s*name:\s*"?([^"\n]*)"?\s*$', block)
+print(mm.group(1).strip() if mm else "")
+PY
+)"
+    [ -n "$name" ] && { printf '%s\n' "$name"; return 0; }
+  fi
+  printf 'linear\n'
+}
+
+# Directory holding provider implementations (sibling of this lib).
+tp_providers_dir() {
+  local here
+  here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  printf '%s/../providers\n' "$here"
+}
+
+# Dispatch one operation to the active provider.
+tp() {
+  local op="${1:-}"; shift || true
+  [ -n "$op" ] || { echo "tp: missing operation" >&2; return 2; }
+
+  local name impl
+  name="$(tp_provider_name)"
+  impl="$(tp_providers_dir)/${name}.sh"
+
+  if [ ! -f "$impl" ]; then
+    echo "tp: unknown ticket provider '$name' (no $impl)" >&2
+    return 2
+  fi
+
+  TICKET_PROVIDER="$name" sh "$impl" "$op" "$@"
+}
+
+# Normalized states the engine reasons in. Adapters map these to provider terms.
+TP_STATES="backlog unstarted started in_review completed"
+
+tp_is_valid_state() {
+  case " $TP_STATES " in
+    *" $1 "*) return 0 ;;
+    *) return 1 ;;
+  esac
+}