@delorenj/pjangler 1.2.18 → 1.2.21

package/templates/hermes-agent/docs/architecture.md

@@ -92,23 +92,20 @@ happen to share a token, the second one's startup fails fast. The N×M cost
 (N BotFather sessions per fleet) is the price we accept for zero custom
 routing code.
 
-## One Ticket Board Per Repo
+## One Plane project per agent
 
-The configured ticket board is the natural unit of work isolation. The PM owns
-one board per repo and routes worker agents through that shared source of truth,
-so decisions, filters, and review state stay coherent.
+A Plane "project" is the natural unit of work isolation. Mixing agents into a
+shared project would conflate decisions and break filters. 1:1 also makes
+archive-on-retire clean.
 
 ## Bloodbank wiring
 
 Each consumer subscribes to two lanes:
-- `bloodbank.evt.v1.repo.<repo>.>`   — events affecting this repo
-- `bloodbank.cmd.v1.agent.<agent_id>.>` — commands targeting THIS agent specifically
+- `bloodbank.evt.v1.repo.>` — canonical repo-domain events, filtered by `data.repo`
+- `bloodbank.cmd.v1.agent.>` — canonical agent-domain commands, filtered by `data.target_agent_id`
 
 Each agent emits CloudEvents 1.0 envelopes with `actor.agent_id`,
 `producer = hermes-agent:<id>`, `source = hermes://agent/<id>`. The naming
-spec is owned by Holyfields (`~/code/33GOD/bloodbank/docs/event-naming.md`).
-
-The current generated consumer is a transitional NATS receiver and audit
-capture. The target architecture is a first-class Hermes Bloodbank gateway where
-command events enter the same turn queue as Telegram/web messages; see
-[Bloodbank Gateway](bloodbank-gateway.md).
+contract is owned by Bloodbank (`~/code/33GOD/bloodbank/docs/event-naming.md`).
+Repo and agent identifiers belong in envelope data, actor, or source fields,
+never in type or subject tokens.

package/templates/hermes-agent/docs/fleet-control-plane/README.md

@@ -24,7 +24,6 @@ The Fleet remains a set of independently useful parts:
 - [prd.md](./prd.md) - Functional and non-functional requirements.
 - [architecture.md](./architecture.md) - Technical architecture and ADRs.
 - [epics-and-stories.md](./epics-and-stories.md) - Implementation backlog with acceptance criteria.
-- [n8n-service-hub.md](./n8n-service-hub.md) - Concrete service-hub shape for n8n plus systemd fallback.
 - [implementation-readiness-report-2026-06-27.md](./implementation-readiness-report-2026-06-27.md) - Readiness assessment and launch gates.
 
 ## Adapted BMAD Note
@@ -33,3 +32,4 @@ The formal BMAD workflow expects a project-local `_bmad` runtime, PRD, and
 step-by-step user confirmations. This repo does not currently contain `_bmad`.
 These artifacts preserve the BMAD intent and structure while using the live
 architecture review and advanced elicitation decisions as input.
+

package/templates/hermes-agent/docs/operations.md

@@ -29,7 +29,7 @@ invocations).
 | 10 hermes profile | `hermes profile create <repo>-<role> --clone --no-alias` + mirror skills/plugins/hooks from default + symlink canonical runtime skills (`delonet-conventions`, `delonet-dotenv`, `hermes-pm-template-maintenance`, `hindsight`, `subagent-driven-development`) from `/home/delorenj/.agents/skills`; PM roles also seed `VOX_URL` in profile `.env` | n/a |
 | 20 runtime repo | Create gh:delorenj/agent-hm-<repo>-<role> (private), push scaffold from role-local `.runtime-scaffold/`, submodule-add into ./runtime/, symlink ~/.hermes/profiles/<id> → runtime; PM roles also link the Voxxy plugin and set `tts.provider: voxxy` | `SKIP_RUNTIME_REPO=1` |
 | 30 telegram | Capture BotFather token, write to runtime/.env, enable hermes-telegram toolset | `SKIP_TELEGRAM=1` |
-| 42 ticket provider | Create or bind the configured ticket board, patch identifier into role.yaml | `SKIP_PLANE=1` |
+| 40 plane | Create Plane project in 33god workspace (1:1 with agent), patch identifier into role.yaml | `SKIP_PLANE=1` |
 | 60 bloodbank | Install consumer (renders from scaffold w/ agent values), health-check NATS, install nats-py via uv if missing | `SKIP_BLOODBANK=1` |
 | 70 systemd | Install user units: gateway, consumer, heartbeat timer (board-reconciliation sentinel pass + gated runtime checkpoint, one tick) | `SKIP_SYSTEMD=1` |
 | 80 registry | Append entry to ~/.hermes/agents-registry.yaml | n/a |
@@ -118,7 +118,7 @@ systemctl --user start hermes-${AGENT}-gateway.service
 | --- | --- |
 | Telegram | DM `@<repo>_<role>_bot` (once Telegram is wired) |
 | Local CLI | `./agents/hermes/<role>/hermes chat "..."` |
-| Bloodbank | Publish to subject `bloodbank.cmd.v1.agent.<agent_id>.<verb>.requested` |
+| Bloodbank | Publish to `bloodbank.cmd.v1.agent.task.assign` with `data.target_agent_id = <agent_id>` |
 
 ## Inspect fleet state
 
@@ -187,10 +187,10 @@ systemctl --user disable --now hermes-${AGENT}-heartbeat.timer
 #    that's what you want!)
 hermes profile delete ${AGENT}
 
-# 3. Archive the ticket board if the provider supports archival
+# 3. Archive Plane project (Plane UI or API)
 PROJECT_ID=$(python3 -c "import yaml,pathlib; print(yaml.safe_load(pathlib.Path.home().joinpath('.hermes/agents-registry.yaml').read_text())['agents']['${AGENT}']['plane']['project_id'])")
 curl -X POST "https://plane.delo.sh/api/v1/workspaces/33god/projects/${PROJECT_ID}/archive/" \
-  -H "X-API-Key: ${PLANE_API_KEY:-${PLANE_33GOD_API_KEY}}"
+  -H "X-API-Key: ${PLANE_33GOD_API_KEY}"
 
 # 4. BotFather: /deletebot @<repo>_<role>_bot
 # 5. Archive runtime repo (GitHub UI; we don't have delete_repo scope by default)
@@ -219,7 +219,8 @@ rm -rf agents/hermes/<role>
 ### Consumer not seeing events
 - Verify NATS is up: `docker compose -f ~/code/33GOD/bloodbank/compose/docker-compose.yml ps`
 - Tail consumer: `journalctl --user -fu hermes-<agent>-consumer.service`
-- Make sure something is actually publishing to `bloodbank.evt.v1.repo.<repo>.*`
+- Make sure something is publishing canonical repo events such as
+  `bloodbank.evt.v1.repo.issue.updated` with `data.repo = <repo>`
 
 ### Heartbeat not checkpointing (runtime not pushing)
 The checkpoint runs inside the heartbeat tick (after the board-reconciliation

package/templates/hermes-agent/docs/sentinel/README.md

@@ -26,7 +26,7 @@ that does the board-reconciliation pass and then a gated runtime checkpoint
 `.scripts/sentinel/`.
 
 It talks to the ticket board through a pluggable adapter, so the same engine
-runs on Plane or Trello. The engine lives once in this template (the
+runs on Linear, Plane, or Trello. The engine lives once in this template (the
 single source of truth) and propagates to every deployment with
 `copier update`.
 
@@ -37,6 +37,8 @@ The following is true as of June 1, 2026.
 - The engine, the provider abstraction, and the autonomous adversarial-review
   enforcement are built, syntax-clean, and validated offline with a mock
   provider.
+- The **Linear** adapter is verified live against a real board (a real
+  `DEL` team: `resolve`, `list_issues` returning 93 issues, and `get_issue`).
 - The **Plane** adapter is verified live against a real workspace
   (`resolve`, `list_issues`, `get_issue`, `comment`, and a
   `transition` to `completed` on a disposable issue).
@@ -52,7 +54,7 @@ For a local, single-machine install (no GitHub runtime repo, no Telegram, no
 NATS), use the one-command bootstrap. From inside the target project:
 
 ```bash
-export PLANE_33GOD_API_KEY=<key>   # or PLANE_API_KEY / TRELLO_KEY + TRELLO_TOKEN
+export PLANE_API_KEY=<key>   # or LINEAR_API_KEY / TRELLO_KEY + TRELLO_TOKEN
 curl -fsSL https://raw.githubusercontent.com/delorenj/hermes-agent-template/main/install-local.sh | sh
 ```
 
@@ -64,7 +66,7 @@ macOS). See [Development guide: local install](development.md#local-install-one-
 <!-- prettier-ignore -->
 > [!IMPORTANT]
 > Full (non-local) provisioning is outward-facing. It can create a GitHub
-> runtime repo, a Telegram bot, and a ticket board, and the Telegram step is
+> runtime repo, a Telegram bot, and a Plane project, and the Telegram step is
 > interactive. Use `install-local.sh` or the `SKIP_*` flags described in
 > [Development guide:
 > provisioning](development.md#provisioning-the-pm-manual) for local or lean
@@ -77,9 +79,9 @@ All paths are relative to the repository root.
 | Path | What it is |
 | --- | --- |
 | `copier.yml` | Questions (`role`, `ticket_provider`) and the `_tasks` provisioning chain. |
-| `template/role.yaml.jinja` | The rendered role identity/personality manifest. Repo-owned board binding and reconciliation knobs live in repo-root `.project.json`. |
+| `template/role.yaml.jinja` | The rendered role manifest, including the `ticket_provider` binding and the `reconcile` knobs (`grace_hours`, `auto_review`). |
 | `template/.scripts/lib/ticket-provider.sh` | The adapter dispatcher (`tp`). The engine's only seam to a ticket system. |
-| `template/.scripts/providers/{plane,trello}.sh` | The provider adapters. |
+| `template/.scripts/providers/{linear,plane,trello}.sh` | The provider adapters. |
 | `template/.scripts/42-ticket-provider.sh` | Provisioning step that resolves or creates the board. |
 | `template/.scripts/70-systemd.sh` | Provisioning step that installs the gateway, consumer, and the fused `heartbeat` timer (board-reconciliation sentinel pass + gated runtime checkpoint). |
 | `install-local.sh` | One-command local install (no cloud, macOS + Linux). |
@@ -107,8 +109,8 @@ the agent to read at run time. Keep the two in sync when behavior changes.
 
 The highest-value open work, in order:
 
-1. Live-verify the **Trello** adapter against a real board (Plane is done).
-   See [Providers: verifying an
+1. Live-verify the **Trello** adapter against a real board (Linear and Plane are
+   done). See [Providers: verifying an
    adapter](providers.md#verifying-an-adapter-against-a-live-board).
 2. Confirm `install-local.sh` on a real macOS machine. The Linux path and the
    Plane adapter are verified; the macOS `launchd` agent and `mkdir` lock get

package/templates/hermes-agent/docs/sentinel/architecture.md

@@ -71,8 +71,7 @@ function, `tp`, that dispatches to one provider implementation under
 through the `ticket_provider` question and recorded in `role.yaml` under
 `ticket_provider.name`.
 
-This is what lets one engine serve the supported ticket back ends: Plane and
-Trello.
+This is what lets one engine serve three back ends: Trello, Plane, and Linear.
 For the full contract and the per-provider details, see
 [Providers](providers.md).
 

package/templates/hermes-agent/docs/sentinel/development.md

@@ -112,7 +112,7 @@ repository root instead of driving Copier by hand. From inside the target
 project:
 
 ```bash
-export PLANE_33GOD_API_KEY=<key>   # or PLANE_API_KEY / TRELLO_KEY + TRELLO_TOKEN
+export PLANE_API_KEY=<key>   # or LINEAR_API_KEY / TRELLO_KEY + TRELLO_TOKEN
 curl -fsSL https://raw.githubusercontent.com/delorenj/hermes-agent-template/main/install-local.sh | sh
 ```
 
@@ -133,8 +133,8 @@ The script:
 7. smoke-tests the board connection through the adapter.
 
 Useful environment overrides (skip the prompts): `HAT_REPO`, `HAT_PROVIDER`,
-`HAT_ROLES`, `HAT_PLANE_WORKSPACE`, `HAT_PLANE_PROJECT`, `HAT_TRELLO_BOARD`,
-and `HAT_DRY_RUN=1` to preview without changing anything.
+`HAT_ROLES`, `HAT_PLANE_WORKSPACE`, `HAT_PLANE_PROJECT`, `HAT_LINEAR_TEAM`,
+`HAT_TRELLO_BOARD`, and `HAT_DRY_RUN=1` to preview without changing anything.
 
 This local path does not wire Telegram or email. Those are convenience layers in
 the `pjangler` provisioner, not requirements for a working agent — talk to the
@@ -151,7 +151,7 @@ cd /path/to/your-project
 copier copy gh:delorenj/hermes-agent-template ./agents/hermes/pm \
   --data role=pm \
   --data target_repo=<repo> \
-  --data ticket_provider=<plane|trello>
+  --data ticket_provider=<linear|plane|trello>
 ```
 
 The `_tasks` chain in `copier.yml` runs the numbered provisioning scripts in
@@ -162,7 +162,7 @@ order. Several of them reach outside the repository.
 > Full provisioning is outward-facing and partly interactive.
 > `20-runtime-repo.sh` creates a private GitHub repo with `gh repo create`,
 > `30-telegram.sh` prompts for a BotFather token and blocks waiting for input,
-> and `42-ticket-provider.sh` can create a ticket board. Don't run full
+> and `42-ticket-provider.sh` can create a Plane project. Don't run full
 > provisioning unattended.
 
 Use the `SKIP_*` environment flags for a local or lean install. Each numbered
@@ -172,7 +172,7 @@ script checks its flag and skips cleanly.
 | --- | --- |
 | `SKIP_TELEGRAM` | The interactive BotFather token step. |
 | `SKIP_RUNTIME_REPO` | Creating the GitHub runtime repo. |
-| `SKIP_PLANE` | Creating or linking the ticket board. |
+| `SKIP_PLANE` | Creating a Plane project. |
 | `SKIP_BLOODBANK` | Installing the BloodBank consumer. |
 | `SKIP_SYSTEMD` | Installing `systemd` units (gateway, consumer, heartbeat timer). |
 
@@ -181,14 +181,13 @@ For example, a local install that creates no cloud resources:
 ```bash
 SKIP_TELEGRAM=1 SKIP_RUNTIME_REPO=1 SKIP_PLANE=1 SKIP_BLOODBANK=1 \
   copier copy gh:delorenj/hermes-agent-template ./agents/hermes/pm \
-  --data role=pm --data target_repo=<repo> --data ticket_provider=trello
+  --data role=pm --data target_repo=<repo> --data ticket_provider=linear
 ```
 
 After provisioning, set the board binding in
-repo-root `.project.json`. For Trello, set `ticket_provider.board_id` to the
-board id; for Plane, set `ticket_provider.workspace` and `ticket_provider.board_id`.
-Make the provider key available to the heartbeat's environment: on Linux through
-a `systemd` `EnvironmentFile` (for example
+`agents/hermes/pm/role.yaml`. For Linear, set `ticket_provider.team`
+to the team key. Make the provider key available to the heartbeat's environment:
+on Linux through a `systemd` `EnvironmentFile` (for example
 `~/.hermes/<agent_id>.env`); on macOS the `launchd` agent sources that same
 per-agent env file, so write the key there.
 
@@ -257,8 +256,8 @@ These cost real debugging time. Watch for them.
 
 The following work is open for the incoming agent, roughly in priority order.
 
-1. **Live-verify the Trello adapter.** Plane is verified live
-   (including `transition` and `comment`). Trello is implemented against
+1. **Live-verify the Trello adapter.** Linear and Plane are verified live
+   (Plane includes `transition` and `comment`). Trello is implemented against
    the contract but unverified. Follow [Providers: verifying an
    adapter](providers.md#verifying-an-adapter-against-a-live-board) with Trello
    credentials, and fix any endpoint or field mismatches.

package/templates/hermes-agent/docs/sentinel/providers.md

@@ -1,7 +1,7 @@
 # Provider adapters
 
 This guide is the reference for the ticket-provider abstraction: the contract
-every adapter implements, the two adapters that ship today, and a
+every adapter implements, the three adapters that ship today, and a
 step-by-step process for adding a new provider or verifying an existing one
 against a live board. Read [Architecture](architecture.md) first for how the
 adapter fits into the engine.
@@ -43,8 +43,12 @@ maps each to its back end's concrete state.
 
 ## The adapters that ship today
 
-The repository includes two supported adapters with different verification status.
+The repository includes three adapters with different verification status.
 
+- **Linear** (`providers/linear.sh`) is the reference implementation. It uses
+  the Linear GraphQL API. It's verified live against a real board. Linear's
+  `issue(id:)` field accepts both the UUID and the human identifier (for
+  example, `DEL-42`), so the engine can pass identifiers through.
 - **Plane** (`providers/plane.sh`) uses the Plane REST API with `X-API-Key`
   authentication. A Plane project maps to the board, a cycle maps to the
   milestone, and `state.group` maps to the state type. It's verified live. Note
@@ -60,12 +64,26 @@ The repository includes two supported adapters with different verification statu
 
 Set credentials in the environment and the board binding in `role.yaml`.
 
+<details>
+<summary>Linear</summary>
+
+- Credentials: `LINEAR_API_KEY`.
+- Binding:
+
+  ```yaml
+  ticket_provider:
+    name: linear
+    team: DEL # Linear team key
+    project: "" # optional, scopes milestone and issue queries
+  ```
+
+</details>
+
 <details>
 <summary>Plane</summary>
 
-- Credentials: `PLANE_API_KEY` or workspace-specific
-  `PLANE_<WORKSPACE>_API_KEY` from the shared fleet env. Endpoint:
-  `PLANE_BASE` (default `https://plane.delo.sh`).
+- Credentials: `PLANE_API_KEY`. Endpoint: `PLANE_BASE` (default
+  `https://plane.delo.sh`).
 - Binding:
 
   ```yaml
@@ -96,9 +114,8 @@ Set credentials in the environment and the board binding in `role.yaml`.
 
 To add a fourth provider, for example GitHub Issues or Jira, follow these steps.
 
-1. Create `template/.scripts/providers/<name>.sh`. Start from `plane.sh` if it
-   uses REST with a single API key, or `trello.sh` if it has a board/list/card
-   model.
+1. Create `template/.scripts/providers/<name>.sh`. Start from `linear.sh` if the
+   back end uses GraphQL, or `plane.sh` if it uses REST with a single API key.
 2. Implement every operation in [the contract](#the-contract). Return the exact
    JSON shapes shown in the table. Map your back end's states to the five
    normalized states.
@@ -110,7 +127,8 @@ To add a fourth provider, for example GitHub Issues or Jira, follow these steps.
 5. Extend `template/role.yaml.jinja` with a provider-specific binding block
    under the `{% if ticket_provider == '<name>' %}` branch.
 6. Teach `42-ticket-provider.sh` how to resolve or create the board for your
-   provider, if it differs from the existing `plane` and `trello` cases.
+   provider, if it differs from the existing `linear`, `plane`, and `trello`
+   cases.
 7. Validate and verify with the steps below.
 
 <!-- prettier-ignore -->
@@ -140,7 +158,7 @@ Before you touch a live board, confirm the adapter parses and fails cleanly.
    exit, with no Python traceback:
 
    ```bash
-   ( unset PLANE_API_KEY PLANE_33GOD_API_KEY; sh template/.scripts/providers/plane.sh resolve )
+   ( unset LINEAR_API_KEY; sh template/.scripts/providers/linear.sh resolve )
    ```
 
 ## Verifying an adapter against a live board
@@ -151,15 +169,15 @@ never closes or modifies a ticket, so it's safe to run.
 
 ```bash
 # 1. Load the credential into the environment only (never print it).
-export PLANE_API_KEY="$(grep -E '^(export )?PLANE(_[A-Z0-9_]+)?_API_KEY=' \
-  ~/.hermes/<agent>.env | head -1 | sed -E 's/^(export )?PLANE(_[A-Z0-9_]+)?_API_KEY=//; s/^"//; s/"$//')"
+export LINEAR_API_KEY="$(grep -E '^(export )?LINEAR_API_KEY=' \
+  ~/.hermes/<agent>.env | head -1 | sed -E 's/^(export )?LINEAR_API_KEY=//; s/^"//; s/"$//')"
 
 # 2. Stage a role directory bound to the real board.
 T=$(mktemp -d); RD="$T/agents/hermes/pm"
 mkdir -p "$RD/.scripts/lib" "$RD/.scripts/providers"
 cp template/.scripts/lib/ticket-provider.sh "$RD/.scripts/lib/"
-cp template/.scripts/providers/plane.sh "$RD/.scripts/providers/"
-printf 'repo: demo\nrole: pm\nticket_provider:\n  name: plane\n  workspace: 33god\n  project: <project-uuid>\n' \
+cp template/.scripts/providers/linear.sh "$RD/.scripts/providers/"
+printf 'repo: demo\nrole: pm\nticket_provider:\n  name: linear\n  team: DEL\n' \
   > "$RD/role.yaml"
 
 # 3. Run the read operations.
@@ -181,4 +199,5 @@ verification.
 ## Read next
 
 - [Development guide](development.md): the full edit, validate, and propagate
-  workflow, plus the open roadmap, which includes live-verifying Trello.
+  workflow, plus the open roadmap, which includes live-verifying Plane and
+  Trello.

package/templates/hermes-agent/install-local.sh

@@ -15,11 +15,10 @@
 #
 # Environment overrides (skip the prompts):
 #   HAT_REPO=<name>            project/repo name (default: basename of CWD)
-#   HAT_PROVIDER=plane|trello   (default: plane)
+#   HAT_PROVIDER=linear|plane|trello   (default: plane)
 #   HAT_ROLES="pm"                     roles to install (default: pm)
 #   HAT_DRY_RUN=1              print actions, change nothing
-#   Provider creds: PLANE_API_KEY or PLANE_<WORKSPACE>_API_KEY + PLANE_BASE
-#                   | TRELLO_KEY+TRELLO_TOKEN
+#   Provider creds: LINEAR_API_KEY | PLANE_API_KEY+PLANE_BASE | TRELLO_KEY+TRELLO_TOKEN
 set -eu
 
 say()  { printf '\033[36m%s\033[0m\n' "$*"; }
@@ -101,7 +100,7 @@ TOML
 fi
 
 # --- 4. Provider credentials + board binding ---------------------------------
-ask HAT_PROVIDER "Ticket provider (plane|trello)" "plane"
+ask HAT_PROVIDER "Ticket provider (linear|plane|trello)" "plane"
 PROVIDER="$HAT_PROVIDER"
 ask HAT_REPO "Project/repo name" "$(basename "$PROJECT_DIR" | tr '[:upper:]' '[:lower:]')"
 REPO="$HAT_REPO"
@@ -110,17 +109,13 @@ PM_ENV="$HOME/.hermes/${REPO}-pm.env"
 # These get written into the pm role.yaml binding after render.
 # Pre-seed from optional env knobs so the install can run non-interactively.
 TP_WORKSPACE="${HAT_PLANE_WORKSPACE:-}"; TP_PROJECT="${HAT_PLANE_PROJECT:-}"
-TP_BOARD="${HAT_TRELLO_BOARD:-}"
+TP_TEAM="${HAT_LINEAR_TEAM:-}"; TP_BOARD="${HAT_TRELLO_BOARD:-}"
 case "$PROVIDER" in
   plane)
     ask PLANE_BASE "Plane base URL" "https://app.plane.so"
+    : "${PLANE_API_KEY:?Set PLANE_API_KEY in your environment, then re-run}"
     ask TP_WORKSPACE "Plane workspace slug" ""
     [ -n "$TP_WORKSPACE" ] || die "workspace is required"
-    TP_WORKSPACE_KEY="$(printf '%s' "$TP_WORKSPACE" | tr '[:lower:]' '[:upper:]' | sed 's/[^A-Z0-9]/_/g')"
-    TP_WORKSPACE_KEY="PLANE_${TP_WORKSPACE_KEY}_API_KEY"
-    eval "TP_WORKSPACE_API_KEY=\${$TP_WORKSPACE_KEY:-}"
-    PLANE_API_KEY="${PLANE_API_KEY:-$TP_WORKSPACE_API_KEY}"
-    : "${PLANE_API_KEY:?Set PLANE_API_KEY or $TP_WORKSPACE_KEY in your environment, then re-run}"
     say "   Plane projects in '$TP_WORKSPACE':"
     _pj="$(mktemp)"
     curl -fsS "$PLANE_BASE/api/v1/workspaces/$TP_WORKSPACE/projects/?per_page=100" \
@@ -138,9 +133,15 @@ PY
     rm -f "$_pj"
     ask TP_PROJECT "Plane project UUID to manage" ""
     [ -n "$TP_PROJECT" ] || die "project UUID is required"
-    CRED_LINES="$TP_WORKSPACE_KEY=$PLANE_API_KEY
+    CRED_LINES="PLANE_API_KEY=$PLANE_API_KEY
 PLANE_BASE=$PLANE_BASE"
     ;;
+  linear)
+    : "${LINEAR_API_KEY:?Set LINEAR_API_KEY in your environment, then re-run}"
+    ask TP_TEAM "Linear team key (for example DEL)" ""
+    [ -n "$TP_TEAM" ] || die "team key is required"
+    CRED_LINES="LINEAR_API_KEY=$LINEAR_API_KEY"
+    ;;
   trello)
     : "${TRELLO_KEY:?Set TRELLO_KEY in your environment, then re-run}"
     : "${TRELLO_TOKEN:?Set TRELLO_TOKEN in your environment, then re-run}"
@@ -164,13 +165,12 @@ fi
 export SKIP_TELEGRAM=1 SKIP_EMAIL=1 SKIP_RUNTIME_REPO=1 SKIP_PLANE=1 \
        SKIP_BLOODBANK=1 SKIP_SYSTEMD=1
 ROLES="${HAT_ROLES:-pm}"
-SCRUB_PLANE_KEY="${TP_WORKSPACE_KEY:-PLANE_DEFAULT_API_KEY}"
 for ROLE in $ROLES; do
   say "5. provisioning role: $ROLE"
   DEST="$PROJECT_DIR/agents/hermes/$ROLE"
   # Scrub provider creds from copier's environment so 42-ticket-provider skips
   # board CREATION; we bind to the existing board in step 6 instead.
-  run "env -u PLANE_API_KEY -u '$SCRUB_PLANE_KEY' \
+  run "env -u PLANE_API_KEY -u PLANE_33GOD_API_KEY -u LINEAR_API_KEY \
         -u TRELLO_KEY -u TRELLO_TOKEN \
         copier copy '$TEMPLATE_SRC' '$DEST' --trust --defaults --overwrite \
         --data target_repo='$REPO' --data role='$ROLE' --data ticket_provider='$PROVIDER'"
@@ -180,7 +180,7 @@ done
 PM_ROLE="$PROJECT_DIR/agents/hermes/pm/role.yaml"
 if [ -f "$PM_ROLE" ] && [ "${HAT_DRY_RUN:-0}" != "1" ]; then
   say "6. binding pm to your $PROVIDER board"
-  TP_WORKSPACE="$TP_WORKSPACE" TP_PROJECT="$TP_PROJECT" \
+  TP_WORKSPACE="$TP_WORKSPACE" TP_PROJECT="$TP_PROJECT" TP_TEAM="$TP_TEAM" \
   TP_BOARD="$TP_BOARD" PROVIDER="$PROVIDER" python3 - "$PM_ROLE" <<'PY'
 import os, re, sys, pathlib
 p = pathlib.Path(sys.argv[1]); t = p.read_text()
@@ -190,6 +190,7 @@ def setleaf(text, key, val):
     return new if n else text
 t = setleaf(t, "workspace", os.environ.get("TP_WORKSPACE",""))
 t = setleaf(t, "project",   os.environ.get("TP_PROJECT",""))
+t = setleaf(t, "team",      os.environ.get("TP_TEAM",""))
 t = setleaf(t, "board",     os.environ.get("TP_BOARD",""))
 p.write_text(t)
 print("   bound:", {k:v for k,v in os.environ.items() if k.startswith("TP_") and v})

package/templates/hermes-agent/runtime-scaffold/README.md

@@ -13,7 +13,7 @@ and recoverable on failure.
 | `memories/MEMORY.md` | yes | The condensed mental-model summary loaded each session |
 | `memories/USER.md` | yes | The operator's persona (Jarad DeLorenzo, ...) |
 | `sessions/sessions.db` | yes (LFS) | SQLite store of every conversation |
-| `bloodbank-consumer.py` | yes | NATS subscriber for repo-scoped events |
+| `bloodbank-consumer.py` | yes | NATS subscriber using canonical subjects plus envelope routing data |
 | `decisions/` | yes | Agent-emitted decisions, one file per important call |
 | `.env` | **no** | API keys + Telegram bot token (per-machine secret) |
 | `auth.json` | **no** | Deprecated local OAuth store; fleet auth defaults to `HERMES_OAUTH_FILE=~/.hermes/auth.json` |

package/templates/hermes-agent/runtime-scaffold/bloodbank-consumer.py

@@ -3,14 +3,16 @@
 Bloodbank consumer for hermes agent {{agent_id}}.
 
 Subscribes to:
-    bloodbank.evt.v1.repo.{{repo}}.>
-    bloodbank.cmd.v1.agent.{{agent_id}}.>
+    bloodbank.evt.v1.repo.>
+    bloodbank.cmd.v1.agent.>
 
-This scaffold is a transitional receiver: it proves NATS subscription and keeps
-a durable audit copy at $HERMES_HOME/bloodbank-inbox/<timestamp>.json. It is
-not the final command path. Bloodbank command subjects should become a Hermes
-gateway/transport so each consumed event enters the same turn queue as Telegram
-or web input, with backpressure handled by the queue instead of by a file drain.
+The Bloodbank subject identifies the fixed domain/entity/action route. Repo and
+agent identifiers stay in envelope data, so this consumer filters repo events
+by ``data.repo`` and agent commands by ``data.target_agent_id``.
+
+For each event/command received, writes it to the agent's notification queue at
+$HERMES_HOME/bloodbank-inbox/<timestamp>.json so the gateway can ingest it on
+the next tick. Reconnects on broker churn; idempotent across restarts.
 
 Generated by hermes-agent-template/runtime-scaffold/bloodbank-consumer.py and
 rendered with role-specific values at provision time. Re-render by re-running
@@ -49,8 +51,8 @@ PRODUCER = f"hermes-agent:{AGENT_ID}"
 SOURCE   = f"hermes://agent/{AGENT_ID}"
 
 SUBJECTS = [
-    f"bloodbank.evt.v1.repo.{REPO}.>",
-    f"bloodbank.cmd.v1.agent.{AGENT_ID}.>",
+    "bloodbank.evt.v1.repo.>",
+    "bloodbank.cmd.v1.agent.>",
 ]
 
 KIND_MARKERS = {"event": "evt", "command": "cmd", "reply": "rpy"}
@@ -62,8 +64,8 @@ def _now():
 
 def _subject_and_domain(ce_type, kind):
     parts = ce_type.split(".")
-    if len(parts) != 5 or parts[0] != "bloodbank" or not parts[1].startswith("v"):
-        raise ValueError(f"type {ce_type!r} must match bloodbank.vN.<domain>.<entity>.<action>")
+    if len(parts) != 5 or parts[0] != "bloodbank" or parts[1] != "v1":
+        raise ValueError(f"type {ce_type!r} must match bloodbank.v1.<domain>.<entity>.<action>")
     if kind not in KIND_MARKERS:
         raise ValueError(f"unknown envelope kind {kind!r}")
     _vendor, version, domain, entity, action = parts
@@ -95,6 +97,33 @@ def build_envelope(ce_type, data, *, kind="event", correlationid=None, causation
     return env
 
 
+def _is_for_consumer(subject, payload):
+    """Route canonical subjects using identifiers carried in envelope data."""
+    if not isinstance(payload, dict):
+        return False
+    parts = subject.split(".")
+    if len(parts) != 6 or parts[0] != "bloodbank" or parts[2] != "v1":
+        return False
+
+    _vendor, kind, version, domain, entity, action = parts
+    if kind not in KIND_MARKERS.values():
+        return False
+    if KIND_MARKERS.get(payload.get("kind")) != kind:
+        return False
+    if payload.get("subject") != subject:
+        return False
+    if payload.get("type") != f"bloodbank.{version}.{domain}.{entity}.{action}":
+        return False
+    data = payload.get("data")
+    if not isinstance(data, dict):
+        return False
+    if kind == "evt" and domain == "repo":
+        return data.get("repo") == REPO
+    if kind == "cmd" and domain == "agent":
+        return data.get("target_agent_id") == AGENT_ID
+    return False
+
+
 async def main():
     nc = await nats.connect(NATS_URL, name=f"hermes-{AGENT_ID}")
     stop = asyncio.Event()
@@ -103,7 +132,10 @@ async def main():
         try:
             payload = json.loads(msg.data.decode())
         except Exception:
-            payload = {"_raw": msg.data.decode(errors="replace")}
+            sys.stderr.write(f"[bloodbank-consumer:{AGENT_ID}] skipped unroutable payload on {msg.subject}\n")
+            return
+        if not _is_for_consumer(msg.subject, payload):
+            return
         entry = {
             "received_at": _now(),
             "subject": msg.subject,
@@ -125,7 +157,7 @@ async def main():
         "bloodbank.v1.agent.online.changed",
         {"agent_id": AGENT_ID, "repo": REPO, "role": ROLE, "state": "online"},
     )
-    await nc.publish("bloodbank.evt.v1.agent.online.changed", json.dumps(online).encode())
+    await nc.publish(online["subject"], json.dumps(online).encode())
 
     def _shutdown(*_):
         stop.set()
@@ -138,7 +170,7 @@ async def main():
         "bloodbank.v1.agent.online.changed",
         {"agent_id": AGENT_ID, "repo": REPO, "role": ROLE, "state": "offline"},
     )
-    await nc.publish("bloodbank.evt.v1.agent.online.changed", json.dumps(offline).encode())
+    await nc.publish(offline["subject"], json.dumps(offline).encode())
     await nc.drain()
 
 

package/templates/hermes-agent/runtime-scaffold/memories/MEMORY.md

@@ -7,8 +7,8 @@ short and high-signal — anything that should ALWAYS be in context.
 
 You are **{{display_name}}**, the `{{role}}` agent for the `{{repo}}` repo.
 Your scope is the repo at the project root. You communicate via Telegram
-(`@{{repo}}_{{role}}_bot`) and Bloodbank events on the
-`bloodbank.evt.v1.repo.{{repo}}.*` lane.
+(`@{{repo}}_{{role}}_bot`) and canonical Bloodbank repo events on
+`bloodbank.evt.v1.repo.>`, filtered by `data.repo = {{repo}}`.
 
 ## Operator