@delorenj/pjangler 1.2.18 → 1.2.21

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

@@ -62,41 +62,6 @@ p.write_text(new)
 PYEOF
 }
 
-# Locate the repo-root .project.json for this role, if present.
-project_json_path() {
-  local root
-  root="$(project_repo_path 2>/dev/null || true)"
-  [[ -n "$root" && -f "$root/.project.json" ]] && { printf '%s' "$root/.project.json"; return 0; }
-  return 1
-}
-
-# project_json_get <dotted.key> — read a string/scalar from repo-root
-# .project.json. This is the deterministic SOT for project wiring.
-project_json_get() {
-  local key="$1" path
-  path="$(project_json_path 2>/dev/null || true)"
-  [[ -f "$path" ]] || { printf ''; return 0; }
-  python3 - "$path" "$key" <<'PYEOF'
-import json
-import pathlib
-import sys
-
-path, key = sys.argv[1:3]
-try:
-    cur = json.loads(pathlib.Path(path).read_text())
-except Exception:
-    print("", end="")
-    raise SystemExit(0)
-for part in key.split("."):
-    if isinstance(cur, dict) and part in cur:
-        cur = cur[part]
-    else:
-        print("", end="")
-        raise SystemExit(0)
-print(cur if isinstance(cur, (str, int, float, bool)) else "", end="")
-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
@@ -147,10 +112,8 @@ load_role_env() {
   BOT_HANDLE=$(yaml_get telegram.bot_username)
   PROFILE_NAME=$(yaml_get profile)
 
-  # Plane workspace: repo-root .project.json wins; role.yaml is legacy fallback.
-  PLANE_WORKSPACE=$(project_json_get ticket_provider.workspace)
-  [[ -n "$PLANE_WORKSPACE" ]] || PLANE_WORKSPACE=$(yaml_get ticket_provider.workspace)
-  [[ -n "$PLANE_WORKSPACE" ]] || PLANE_WORKSPACE=$(yaml_get plane.workspace)
+  # 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.
@@ -166,27 +129,6 @@ load_role_env() {
          PLANE_WORKSPACE RUNTIME_REPO PROFILE_NAME
 }
 
-plane_workspace_key() {
-  local workspace="${1:-${PLANE_WORKSPACE:-}}"
-  workspace="$(printf '%s' "$workspace" | tr '[:lower:]' '[:upper:]' | sed 's/[^A-Z0-9]/_/g')"
-  [[ -n "$workspace" ]] || workspace="DEFAULT"
-  printf 'PLANE_%s_API_KEY' "$workspace"
-}
-
-resolve_plane_api_key() {
-  if [[ -n "${PLANE_API_KEY:-}" ]]; then
-    export PLANE_API_KEY
-    return 0
-  fi
-  local key value
-  key="$(plane_workspace_key "${1:-${PLANE_WORKSPACE:-}}")"
-  value="${!key:-}"
-  if [[ -n "$value" ]]; then
-    PLANE_API_KEY="$value"
-    export PLANE_API_KEY
-  fi
-}
-
 # Skip a step if previously completed (idempotent reruns).
 already_done() {
   local marker="$ROLE_DIR/.scripts/.done-$1"
@@ -223,7 +165,7 @@ BLOODBANK_COMPOSE_DIR="${BLOODBANK_COMPOSE_DIR:-$(config_get bloodbank.compose_d
 
 # Plane
 PLANE_BASE="${PLANE_BASE:-$(config_get plane.base 'https://plane.delo.sh')}"
-PLANE_API_KEY="${PLANE_API_KEY:-}"
+PLANE_API_KEY="${PLANE_API_KEY:-${PLANE_33GOD_API_KEY:-}}"
 
 export FLEET_ENV HERMES_BIN HERMES_AGENT_REPO HERMES_OAUTH_FILE CODEX_HOME \
        RUNTIME_SCAFFOLD_DIR REGISTRY_FILE \

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

@@ -27,11 +27,6 @@ oauth_file = "~/.hermes/auth.json"
 codex_home = "~/.codex"
 # Canonical external skills dir mirrored into each agent profile.
 canonical_skills_dir = "/home/delorenj/.agents/skills"
-# PM-only external skill libraries surfaced alongside Hermes built-ins.
-pm_external_skill_dirs = [
-  "~/code/skillex/skill-sets/global/.system",
-  "~/code/skillex/packs/bmad/6.10.2",
-]
 # Voxxy plugin + service defaults for Hermes PM agents.
 voxxy_plugin_dir = "~/code/voxxy/plugins/tts/voxxy"
 vox_url = "https://vox.delo.sh"

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

@@ -6,7 +6,7 @@
 # reconciliation pass when local state says no worker is active, the worker
 # heartbeat is stale, or the last full run is outside the cooldown window. The
 # full pass executes the role's sentinel.prompt.md, which reasons about tickets
-# through the ticket-provider adapter (Plane | Trello) — never a
+# through the ticket-provider adapter (Linear | Plane | Trello) — never a
 # hardcoded backend. After the sentinel decision (skip OR full), it
 # opportunistically checkpoints the runtime submodule (commit+push) at most once
 # per HEARTBEAT_CHECKPOINT_MIN_INTERVAL_SECONDS, so memory/session state stays
@@ -19,18 +19,12 @@ PROMPT_FILE="$ROLE_DIR/.scripts/sentinel.prompt.md"
 STATE_FILE="$RUNTIME/continuous-ticket-sentinel-state.json"
 LOCK_FILE="$RUNTIME/continuous-ticket-sentinel.lock"
 ROLE_YAML="$ROLE_DIR/role.yaml"
-FLEET_ENV="${HERMES_FLEET_ENV:-$HOME/.hermes/fleet.env}"
 LOG_FILE="$RUNTIME/logs/heartbeat.log"
 CHECKPOINT_BIN="$ROLE_DIR/.scripts/checkpoint.sh"
 CHECKPOINT_STAMP="$RUNTIME/.last-checkpoint"
 
-if [[ -f "$FLEET_ENV" ]]; then
-  # shellcheck disable=SC1090
-  source "$FLEET_ENV"
-fi
-
 # Hermes binary: explicit env > ~/.config/hermes-agent/hermes-bin > PATH.
-HERMES_BIN="${HERMES_BIN:-${HERMES_FLEET_BIN:-}}"
+HERMES_BIN="${HERMES_BIN:-}"
 if [[ -z "$HERMES_BIN" ]]; then
   if [[ -r "$HOME/.config/hermes-agent/hermes-bin" ]]; then
     HERMES_BIN="$(cat "$HOME/.config/hermes-agent/hermes-bin")"
@@ -86,61 +80,13 @@ print(value.strip().strip('"').strip("'"))
 PYEOF
 }
 
-repo_root() {
-  local dir="$ROLE_DIR"
-  for _ in 1 2 3 4 5; do
-    dir="$(dirname "$dir")"
-    if [[ -d "$dir/.git" || -f "$dir/.git" ]]; then printf '%s\n' "$dir"; return 0; fi
-  done
-  return 1
-}
-REPO_ROOT="$(repo_root)"
-PROJECT_JSON="$REPO_ROOT/.project.json"
-
-project_json_value() {
-  python3 - "$PROJECT_JSON" "$1" <<'PYEOF'
-import json
-import pathlib
-import sys
-
-path, key = sys.argv[1:3]
-try:
-    cur = json.loads(pathlib.Path(path).read_text())
-except Exception:
-    print("")
-    raise SystemExit(0)
-for part in key.split("."):
-    if isinstance(cur, dict) and part in cur:
-        cur = cur[part]
-    else:
-        print("")
-        raise SystemExit(0)
-print(cur if isinstance(cur, (str, int, float, bool)) else "")
-PYEOF
-}
-
-# Project-owned automation gate. Legacy role.yaml reconcile.enabled is honored
-# only for older agents that have not migrated their .project.json yet.
+# True only when role.yaml has a reconcile: block with enabled: true. Block-aware
+# so an unrelated `enabled:` leaf elsewhere in the file can't flip it on.
 reconcile_enabled() {
-  python3 - "$PROJECT_JSON" "$ROLE_YAML" <<'PYEOF'
-import json
-import re
-import sys
+  python3 - "$ROLE_YAML" <<'PYEOF'
+import re, sys
 from pathlib import Path
-project_path, role_path = map(Path, sys.argv[1:3])
-try:
-    project = json.loads(project_path.read_text())
-except Exception:
-    project = {}
-reconcile = ((project.get("automation") or {}).get("reconcile") or {}) if isinstance(project, dict) else {}
-if "enabled" in reconcile:
-    value = reconcile.get("enabled")
-    print("true" if str(value).lower() == "true" else "false")
-    raise SystemExit(0)
-try:
-    text = role_path.read_text()
-except Exception:
-    text = ""
+text = Path(sys.argv[1]).read_text()
 m = re.search(r'(?m)^reconcile:[ \t]*\n((?:[ \t]+\S.*\n?)*)', text)
 block = m.group(1) if m else ""
 me = re.search(r'(?m)^[ \t]+enabled:[ \t]*"?([A-Za-z]+)"?', block)
@@ -150,8 +96,17 @@ PYEOF
 
 AGENT_ID="$(yaml_value agent_id)"
 REPO_NAME="$(yaml_value repo)"
-PROVIDER="$(project_json_value ticket_provider.type)"
-[[ -n "$PROVIDER" ]] || PROVIDER="$(yaml_block_value ticket_provider name)"
+PROVIDER="$(yaml_block_value ticket_provider name)"
+
+repo_root() {
+  local dir="$ROLE_DIR"
+  for _ in 1 2 3 4 5; do
+    dir="$(dirname "$dir")"
+    if [[ -d "$dir/.git" || -f "$dir/.git" ]]; then printf '%s\n' "$dir"; return 0; fi
+  done
+  return 1
+}
+REPO_ROOT="$(repo_root)"
 cd "$REPO_ROOT"
 mkdir -p "$RUNTIME/logs"
 
@@ -177,10 +132,11 @@ else
 fi
 
 # Reconcile gate: the autonomous board-reconciliation pass runs only when
-# repo-root .project.json automation.reconcile.enabled is true. Default off →
-# the heartbeat just checkpoints (legacy checkpoint-timer behavior).
+# role.yaml's reconcile.enabled is true. Default off → the heartbeat just
+# checkpoints (behaves like the legacy hourly checkpoint timer). Flip
+# reconcile.enabled to opt a repo into autonomous board reconciliation.
 if [[ "$(reconcile_enabled)" != "true" ]]; then
-  printf '[heartbeat] reconcile disabled (automation.reconcile.enabled != true) — checkpoint-only tick\n'
+  printf '[heartbeat] reconcile disabled (reconcile.enabled != true) — checkpoint-only tick\n'
   maybe_checkpoint
   exit 0
 fi
@@ -273,6 +229,17 @@ state.update({"source":"hermes-continuous-ticket-sentinel","agent_id":agent_id,"
 tmp = path.with_suffix(path.suffix + ".tmp"); tmp.write_text(json.dumps(state, indent=2, sort_keys=True)+"\n"); tmp.replace(path)
 PYEOF
 
+# Coexistence WIP=1 lease (momo E2/S2.3): don't full-drive if the human-drivable
+# Momo holds it — it's driving the same board. A crashed holder's lease expires
+# (ttl) so the board is never wedged. Release on any exit.
+WIP_LOCK="$RUNTIME/wip-driver.lock"
+if ! python3 "$ROLE_DIR/.scripts/momo-wip-lock.py" acquire "$WIP_LOCK" "hermes:$AGENT_ID" --ttl 3600 >/dev/null 2>&1; then
+  printf '[heartbeat] WIP lease held by Momo — skipping full reconcile pass this tick\n'
+  maybe_checkpoint
+  exit 0
+fi
+trap 'python3 "$ROLE_DIR/.scripts/momo-wip-lock.py" release "$WIP_LOCK" "hermes:$AGENT_ID" >/dev/null 2>&1 || true' EXIT
+
 prompt="$(<"$PROMPT_FILE")"
 set +e
 env HERMES_HOME="$RUNTIME" "$HERMES_BIN" chat -Q --source cron --max-turns 90 -q "$prompt"

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

@@ -1,10 +1,10 @@
 # shellcheck shell=bash
 # Ticket-provider adapter dispatcher — the single seam between the heartbeat
-# sentinel engine and a concrete ticket system (Plane | Trello).
+# 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. Repo-root .project.json owns the
-# provider/board binding; role.yaml is only a legacy provider-name fallback.
+# 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}
@@ -19,7 +19,7 @@
 #   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 repo-root .project.json.
+# 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 /
@@ -64,7 +64,7 @@ PY
 )"
     [ -n "$name" ] && { printf '%s\n' "$name"; return 0; }
   fi
-  printf 'plane\n'
+  printf 'linear\n'
 }
 
 # Directory holding provider implementations (sibling of this lib).
@@ -81,10 +81,6 @@ tp() {
 
   local name impl
   name="$(tp_provider_name)"
-  case "$name" in
-    plane|trello) ;;
-    *) echo "tp: unsupported ticket provider '$name' (expected plane|trello)" >&2; return 2 ;;
-  esac
   impl="$(tp_providers_dir)/${name}.sh"
 
   if [ ! -f "$impl" ]; then

package/templates/hermes-agent/template/.scripts/momo-wip-lock.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""momo-wip-lock — shared WIP=1 driver lease so interactive Momo and the Hermes
+sentinel never double-drive one board (momo E2/S2.3, the coexistence gate).
+
+Both drivers acquire the SAME advisory lease (a JSON file, conventionally
+<runtime>/wip-driver.lock) before a board-driving pass. The lease PERSISTS across
+processes — it is deliberately NOT a held flock, because a Momo pass spans many
+separate tool-call/bash invocations over minutes. flock is used only to serialize
+the check-and-set so two acquirers can't race. A lease is respected while its
+heartbeat is fresh (now - heartbeat_at < ttl); a stale lease (holder died without
+releasing) can be stolen after it expires.
+
+Owners are free strings by convention: "momo" (interactive) or
+"hermes:<agent_id>" (the sentinel). WIP=1 is per BOARD == per runtime, so there
+is one lease file per runtime.
+
+Protocol:
+  * Driver start:  acquire <lock> <me>   -> exit 0 → drive; exit 1 → HELD, back off.
+  * While driving: refresh <lock> <me>   periodically (< ttl) so the lease stays fresh.
+  * Driver end:    release <lock> <me>.
+  * A holder that crashed leaves a lease that expires after `ttl`; the next driver
+    acquires it normally (or `--steal` to take an explicitly stale one immediately).
+
+Commands (exit 0 = you hold it; 1 = someone else holds it fresh; 2 = usage/error):
+  acquire <lockfile> <owner> [--ttl S] [--steal]
+  refresh <lockfile> <owner>
+  release <lockfile> <owner>
+  status  <lockfile>                     # always exit 0
+"""
+from __future__ import annotations
+import argparse, fcntl, json, os, socket, sys, tempfile, time
+
+
+def _read(path: str):
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except Exception:
+        return None
+
+
+def _fresh(lease: dict | None, now: float) -> bool:
+    return bool(lease) and (now - lease.get("heartbeat_at", 0)) < lease.get("ttl", 300)
+
+
+def _write_atomic(path: str, data: dict) -> None:
+    d = os.path.dirname(os.path.abspath(path)) or "."
+    fd, tmp = tempfile.mkstemp(dir=d)
+    with os.fdopen(fd, "w") as f:
+        json.dump(data, f)
+    os.replace(tmp, path)
+
+
+def _guard(lockfile: str):
+    """Sibling .flock file held only for the read-modify-write critical section."""
+    g = open(lockfile + ".flock", "a")
+    fcntl.flock(g, fcntl.LOCK_EX)
+    return g
+
+
+def acquire(lockfile: str, owner: str, ttl: int, steal: bool) -> int:
+    now = time.time(); g = _guard(lockfile)
+    try:
+        cur = _read(lockfile)
+        if cur and cur.get("owner") != owner and _fresh(cur, now) and not steal:
+            print(f"HELD by {cur['owner']} (fresh, {int(now - cur['heartbeat_at'])}s ago) — back off")
+            return 1
+        started = cur["started_at"] if (cur and cur.get("owner") == owner and "started_at" in cur) else now
+        _write_atomic(lockfile, {
+            "owner": owner, "pid": os.getpid(), "host": socket.gethostname(),
+            "started_at": started, "heartbeat_at": now, "ttl": ttl,
+        })
+        print(f"ACQUIRED by {owner}" + (" (stole stale lease)" if (cur and cur.get('owner') != owner) else ""))
+        return 0
+    finally:
+        fcntl.flock(g, fcntl.LOCK_UN); g.close()
+
+
+def refresh(lockfile: str, owner: str) -> int:
+    now = time.time(); g = _guard(lockfile)
+    try:
+        cur = _read(lockfile)
+        if not cur or cur.get("owner") != owner:
+            print(f"NOT OWNER (held by {cur.get('owner') if cur else 'nobody'}) — cannot refresh")
+            return 1
+        cur["heartbeat_at"] = now
+        _write_atomic(lockfile, cur); print("REFRESHED"); return 0
+    finally:
+        fcntl.flock(g, fcntl.LOCK_UN); g.close()
+
+
+def release(lockfile: str, owner: str) -> int:
+    g = _guard(lockfile)
+    try:
+        cur = _read(lockfile)
+        if cur and cur.get("owner") != owner:
+            print(f"NOT OWNER (held by {cur['owner']}) — not releasing"); return 1
+        try:
+            os.remove(lockfile)
+        except FileNotFoundError:
+            pass
+        print("RELEASED"); return 0
+    finally:
+        fcntl.flock(g, fcntl.LOCK_UN); g.close()
+
+
+def status(lockfile: str) -> int:
+    now = time.time(); cur = _read(lockfile)
+    if not cur:
+        print("FREE (no lease)"); return 0
+    state = "fresh" if _fresh(cur, now) else "STALE"
+    print(f"{cur['owner']} — {state} (heartbeat {int(now - cur.get('heartbeat_at', 0))}s ago, "
+          f"ttl {cur.get('ttl')}s, pid {cur.get('pid')}@{cur.get('host')})")
+    return 0
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("cmd", choices=["acquire", "refresh", "release", "status"])
+    ap.add_argument("lockfile")
+    ap.add_argument("owner", nargs="?")
+    ap.add_argument("--ttl", type=int, default=300, help="freshness window in seconds (default 300)")
+    ap.add_argument("--steal", action="store_true", help="take an explicitly stale lease immediately")
+    a = ap.parse_args()
+    if a.cmd in ("acquire", "refresh", "release") and not a.owner:
+        print("owner required", file=sys.stderr); return 2
+    if a.cmd == "acquire":
+        return acquire(a.lockfile, a.owner, a.ttl, a.steal)
+    if a.cmd == "refresh":
+        return refresh(a.lockfile, a.owner)
+    if a.cmd == "release":
+        return release(a.lockfile, a.owner)
+    return status(a.lockfile)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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