@delorenj/pjangler 1.2.21 → 1.2.33

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

@@ -1,204 +0,0 @@
-# Heartbeat sentinel architecture
-
-This guide explains how the heartbeat sentinel engine works: the heartbeat loop,
-the provider abstraction, the normalized state model, and the autonomous
-adversarial-review protocol. Read the [handoff overview](README.md) first for the
-big picture and the file map.
-
-## Who owns it
-
-The sentinel is owned by the unified `pm` role. It's materialized into a project
-at `agents/hermes/pm/`, where the PM carries its `role.yaml`, runtime, the
-sentinel prompt, the enforcement tools under `.scripts/sentinel/`, and the
-heartbeat runner. There is no separate `scrum-master` role; its
-continuous-ticket-sentinel duties fold into the PM and run out-of-band on the
-PM's heartbeat timer.
-
-You provision it by provisioning the PM: run Copier with `--data role=pm` (the
-`70-systemd.sh` step installs the fused `heartbeat` timer that drives the
-sentinel). For the exact commands, see [Development guide:
-provisioning](development.md#provisioning-the-pm-manual).
-
-## The heartbeat loop
-
-A scheduler (`systemd` timer on Linux, `launchd` agent on macOS) fires the
-runner, `template/.scripts/heartbeat.sh`, about once a minute. Each tick fuses
-two jobs: a board-reconciliation **sentinel pass** and a **gated runtime
-checkpoint**. The sentinel pass is a cheap heartbeat that decides whether a
-full, LLM-backed reconciliation pass is worth running; the checkpoint
-(commit+push of the runtime submodule) is gated to at most once an hour. This
-keeps cost low while staying responsive.
-
-The sentinel reads the work-state file,
-`runtime/continuous-ticket-sentinel-state.json`, and chooses one of these
-decisions:
-
-- `skip:active-worker`: a healthy worker process is already moving the active
-  ticket, so there's nothing to do.
-- `skip:cooldown`: a full pass ran too recently (within
-  `SENTINEL_FULL_RUN_COOLDOWN_SECONDS`, default 300).
-- `skip:blocker-cooldown`: the project is blocked and a full pass ran within
-  `SENTINEL_BLOCKED_FULL_RUN_COOLDOWN_SECONDS`, default 900. This is the
-  back-off that prevents a blocked project from burning passes.
-- `run:full`: none of the above hold, so the runner executes a full pass.
-
-A full pass runs `hermes chat` with the rendered prompt,
-`sentinel.prompt.md`. The prompt tells the agent to reconcile
-the board, the local evidence, and live worker state, then either delegate one
-worker, monitor the active worker, run an autonomous adversarial review, or
-record a blocker. A pass never ends in a "looks good, waiting on the operator"
-state: the adversarial review acts on its own verdict.
-
-The runner writes the outcome back to the state file so dashboards and the next
-heartbeat can read it. The required fields are `source`, `agent_id`, `repo`,
-`ticket_provider`, `status`, `summary`, `reason`, `updated_at`,
-`last_activity_at`, and `log_path`. The `status` is one of `idle`, `checking`,
-`active`, `blocked`, `stalled`, or `error`.
-
-<!-- prettier-ignore -->
-> [!NOTE]
-> The heartbeat must never use the state file's own modification time as a
-> liveness signal. The heartbeat rewrites that file every minute, which would
-> make a stale lane look perpetually fresh. The runner uses recorded worker
-> process markers and `last_activity_at` instead.
-
-## The provider abstraction
-
-The engine never calls a ticket system directly. It calls a normalized adapter
-contract, `template/.scripts/lib/ticket-provider.sh`, which exposes a single
-function, `tp`, that dispatches to one provider implementation under
-`template/.scripts/providers/`. The active provider is chosen at provision time
-through the `ticket_provider` question and recorded in `role.yaml` under
-`ticket_provider.name`.
-
-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).
-
-### Normalized states
-
-The engine reasons in provider-neutral states. Each adapter maps these to the
-concrete states, groups, or lists of its back end.
-
-| Normalized state | Meaning |
-| --- | --- |
-| `backlog` | Not yet ready to start. |
-| `unstarted` | Ready, not started. |
-| `started` | A worker is actively implementing. |
-| `in_review` | Implementation complete, awaiting review. |
-| `completed` | Done. |
-
-The mapping is configurable per project in `role.yaml` under
-`ticket_provider`, so non-standard boards still work. For example, you can set
-`in_review: "In Review"` and `completed: "Done"` to match your board's column
-names.
-
-## Autonomous adversarial review (act, do not wait)
-
-This is the **normal per-pass path** for a ticket that has reached review: an
-independent, rigorous **adversarial review** that renders a verdict and the loop
-**acts on it autonomously**. It is not a narrow escape hatch and not an exception
-to a no-close rule — it is how reviewed work moves. The full protocol ships into
-each deployment at
-`template/.scripts/sentinel/docs/autonomous-delegated-review.md`. Here's the
-shape.
-
-When the sentinel finds a ticket in the review lane, it delegates the review to
-an **independent** reviewer. There is no mandatory grace window:
-`reconcile.grace_hours` defaults to `0`, so the reviewer acts immediately. It
-remains an optional operator knob — set it `>0` to reintroduce a deliberate wait
-— but the default never parks completed work waiting on the operator. The
-reviewer must not be the agent that implemented the ticket. Acting as an
-adversarial microscope, the reviewer tries to break the work, checking it against
-the operator's **locked intent**: the acceptance criteria, the active milestone,
-the project's horizon model, and the product north star.
-
-The reviewer then runs the decision gate:
-
-```bash
-.scripts/sentinel/bin/issue-autonomous-review.sh <ISSUE> <REPORT> --close
-```
-
-This script couples four checks so an acceptance can't slip through on a weak
-basis:
-
-1. The close gate passes (`issue-close-gate.sh` confirms the evidence file is
-   complete).
-2. The reviewer attests independence from the implementer.
-3. Drift is `none` or `minor`, never `significant`.
-4. There are no unresolved critical or high findings.
-
-If all four hold, the script renders an `accepted` verdict and emits a decision
-event with `decision=accepted`. **Treat review as done:** an accepted `in_review`
-ticket counts as `completed` for dependents and flow, so downstream work is
-unblocked immediately. By default the ticket **stays in the review lane**, which
-serves as the operator's deferred-QA queue — it is not auto-transitioned to
-`completed`. The `--close` flag is optional (an operator QA sweep can use it to
-drive `tp transition <id> completed`); the normal loop omits it. If any check
-fails, the ticket goes back to / stays active and the script emits
-`decision=held` with the reason. When in doubt, it holds.
-
-This is an adversarial review, not a lightweight or sanity check — the reviewer
-is hard to satisfy. It never clears tickets blocked on credentials, external
-access, paid actions, or undecided product decisions. Those genuine out-of-scope
-blockers are recorded and waited on exactly as before.
-
-### Downstream regression rollback
-
-Deferring operator QA buys speed, and the safety valve is a downstream regression
-rollback. If a later dependent proves a review-accepted feature is **actually
-broken**, the loop moves that feature back to active (`started` if a worker takes
-it now, else `unstarted`) as a prerequisite of the dependent, comments naming the
-dependent and the symptom, and emits
-
-```text
-bloodbank.v1.repo.<repo>.issue.review_rollback.recorded
-```
-
-carrying `{issue, surfaced_by, reason}`. The dependent stays blocked on the
-prerequisite until the fix lands. This is expected and healthy — it is the trade
-for deferring operator QA, not a failure of the review.
-
-### Decision events
-
-Every adversarial-review decision, whether `accepted` or `held`, emits a local
-BloodBank-style event:
-
-```text
-bloodbank.v1.repo.<repo>.issue.autonomous_review.decided
-```
-
-The event carries `issue`, `decision`, `drift`, `close_gate`, `reviewer_agent`,
-`evidence_file`, and `report_file`. Together with the
-`issue.review_rollback.recorded` event it forms the operator's queryable
-accountability trail for every autonomous decision. The emitter is
-`template/.scripts/sentinel/bin/emit-event.py`, and the event types are
-documented in `template/.scripts/sentinel/docs/bloodbank-events.md`. Events
-append to `_bmad-output/implementation-artifacts/bloodbank-events.jsonl`, a
-local spool that doesn't require NATS, so the loop stays reliable offline.
-
-## How the parts connect
-
-A full pass moves through these components in order:
-
-1. The scheduler (`systemd` timer or `launchd` agent) triggers the heartbeat
-   runner (`heartbeat.sh`).
-2. The runner's sentinel logic decides `run:full` and calls `hermes chat` with
-   the prompt.
-3. The agent reads the runtime protocol docs and reconciles state by calling
-   `tp` (the adapter) for board data.
-4. The agent delegates a worker, monitors one, records a blocker, or runs an
-   autonomous adversarial review.
-5. An adversarial review runs the enforcement tools in `.scripts/sentinel/bin/`,
-   which render an `accepted` or `held` verdict and emit a decision event; the
-   loop acts on the verdict (treat as done and unblock dependents, or send the
-   ticket back to active) without waiting on the operator.
-6. The runner writes the outcome to the state file for the next tick, then
-   opportunistically checkpoints the runtime (gated to ~hourly) before exiting.
-
-## Read next
-
-- [Providers](providers.md): the adapter contract and how to add or verify a
-  provider.
-- [Development guide](development.md): editing, validating, propagating, and the
-  open roadmap.

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

@@ -1,277 +0,0 @@
-# Heartbeat sentinel development guide
-
-This guide covers the day-to-day work of changing the heartbeat sentinel engine:
-how to edit it, how to validate changes locally, how to provision and propagate
-it, and what to watch out for. It closes with the open roadmap. Read the
-[handoff overview](README.md) and [Architecture](architecture.md) first.
-
-## Two doc trees, kept in sync
-
-The engine has two documentation trees, and they serve different readers. When
-you change behavior, update both.
-
-- `docs/sentinel/` (this directory) holds the **developer** docs for working
-  on the template.
-- `template/.scripts/sentinel/docs/` holds the **runtime** protocol docs
-  that render into every provisioned project. The running agent reads these at
-  run time. They are `autonomous-delegated-review.md`,
-  `continuous-ticket-orchestration.md`, and `bloodbank-events.md`.
-
-## Making a change
-
-Most engine logic lives under `template/.scripts/sentinel/` and
-`template/.scripts/providers/`, and the heartbeat runner is
-`template/.scripts/heartbeat.sh`. The flow is the same for any change.
-
-1. Edit the runner, the engine file, the adapter, or the prompt.
-2. Validate locally with the steps in [Validating changes
-   locally](#validating-changes-locally).
-3. If you changed behavior, update the runtime protocol docs and these developer
-   docs.
-4. Commit. Deployments pick up the change with `copier update` (see
-   [Propagating changes](#propagating-changes)).
-
-The prompt is a Jinja template,
-`template/.scripts/sentinel.prompt.md.jinja` (rendered to
-`.scripts/sentinel.prompt.md`). It uses `{{ display_name }}`,
-`{{ target_repo }}`, `{{ role }}`, and `{{ ticket_provider }}`. Copier renders
-it during provisioning.
-
-## Validating changes locally
-
-You can validate everything except live-board behavior without credentials.
-
-First, check shell syntax across the engine:
-
-```bash
-for f in template/.scripts/lib/ticket-provider.sh \
-         template/.scripts/providers/*.sh \
-         template/.scripts/heartbeat.sh \
-         template/.scripts/sentinel/bin/*.sh; do
-  sh -n "$f" || bash -n "$f" || echo "FAIL $f"
-done
-```
-
-Next, check the inline Python blocks. The shell scripts embed Python in `<<'PY'`
-heredocs and `python3 -c '...'` calls, and a quoting mistake there only surfaces
-at run time. This extraction script parses each block:
-
-```bash
-python3 - <<'PY'
-import re, pathlib, ast
-import glob
-bad = 0
-for f in glob.glob("template/.scripts/**/*.sh", recursive=True):
-    text = pathlib.Path(f).read_text()
-    for m in re.finditer(r"<<'PY'\n(.*?)\nPY\b", text, re.S):
-        try: ast.parse(m.group(1))
-        except SyntaxError as e: bad += 1; print(f"heredoc {f}: {e}")
-    for m in re.finditer(r"python3 -c '(.*?)'", text, re.S):
-        try: ast.parse(m.group(1))
-        except SyntaxError as e: bad += 1; print(f"inline {f}: {e}")
-print("OK" if not bad else f"{bad} FAILED")
-PY
-```
-
-Finally, run the enforcement quartet end to end with a mock provider. This
-proves the accept and hold branches, the decision-event emission, and the
-optional adapter-based transition without touching a real board.
-
-<details>
-<summary>Mock-provider end-to-end test</summary>
-
-```bash
-T=$(mktemp -d); RD="$T/agents/hermes/pm"
-mkdir -p "$RD/.scripts/lib" "$RD/.scripts/providers" "$RD/.scripts/sentinel/bin" \
-         "$T/_bmad-output/implementation-artifacts/issue-evidence"
-( cd "$T" && git init -q && git config user.email t@t && git config user.name t )
-cp template/.scripts/lib/ticket-provider.sh "$RD/.scripts/lib/"
-cp template/.scripts/sentinel/bin/* "$RD/.scripts/sentinel/bin/"
-printf 'repo: demo\nrole: pm\nagent_id: demo-pm\nticket_provider:\n  name: fake\nreconcile:\n  grace_hours: 0\n  auto_review: true\n' > "$RD/role.yaml"
-printf '#!/usr/bin/env sh\nop="$1"; shift 2>/dev/null||true\ncase "$op" in\n transition) echo "FAKE $1 -> $2" >&2; echo ok;;\n comment) echo okc;; *) echo f;; esac\n' > "$RD/.scripts/providers/fake.sh"
-chmod +x "$RD/.scripts/providers/fake.sh" "$RD/.scripts/sentinel/bin/"*.sh
-EV="$T/_bmad-output/implementation-artifacts/issue-evidence"
-printf '## Issue\n- Worker: codex\n## Acceptance Criteria\n- AC1: done\n## Repo Changes\n- x\n## Verification\n- Command: t\n- Result: pass\n## Ledger Update\n- Ledger updated: yes\n## Known Gaps\n- None\n## Close Recommendation\nClose recommendation: ready\n' > "$EV/TIC-1.md"
-printf '## Reviewer\n- Reviewer agent: rev\n- Independent of implementer: yes\n## Locked Intent Baseline\n- Acceptance criteria source: board\n## Drift Assessment\n- Drift assessment: none\n## Adversarial Findings\n- Critical/high findings: none\n## Decision\n- Decision: accept\n' > "$EV/TIC-1.review.md"
-export BLOODBANK_EVENTS_LOG="$T/e.jsonl"
-bash "$RD/.scripts/sentinel/bin/issue-autonomous-review.sh" TIC-1 "$EV/TIC-1.review.md" --close
-rm -rf "$T"
-```
-
-A passing run prints `ACCEPTED — treat as done (no human wait)`,
-`FAKE TIC-1 -> completed` (from the optional `--close` sweep this test passes),
-and exits 0.
-
-</details>
-
-## Local install (one command)
-
-For a local, single-machine deploy — the lowest-friction path, and the right
-one for handing the system to someone else — use `install-local.sh` at the
-repository root instead of driving Copier by hand. From inside the target
-project:
-
-```bash
-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
-```
-
-The script:
-
-1. installs `hermes` (its own installer) and `copier` if either is missing,
-2. writes a host-correct local `config.toml` (detects the hermes binary, leaves
-   cloud fields blank) if one doesn't exist,
-3. lists the boards on the chosen provider and prompts for the one to manage,
-4. provisions the `pm` role through Copier with all cloud, Telegram, and the
-   gateway step skipped,
-5. binds the PM to the existing board (it never creates one — it scrubs the
-   provider key from Copier's environment so `42-ticket-provider.sh` skips board
-   creation),
-6. installs the PM's heartbeat timer (board-reconciliation sentinel pass + gated
-   runtime checkpoint) as a `launchd` agent on macOS or a `systemd` timer on
-   Linux,
-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_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
-agent with `agents/hermes/pm/hermes chat "..."` and let the sentinel run on its
-heartbeat timer.
-
-## Provisioning the PM (manual)
-
-To drive Copier directly instead of using `install-local.sh`, provision the PM
-with:
-
-```bash
-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=<linear|plane|trello>
-```
-
-The `_tasks` chain in `copier.yml` runs the numbered provisioning scripts in
-order. Several of them reach outside the repository.
-
-<!-- prettier-ignore -->
-> [!CAUTION]
-> 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 Plane project. Don't run full
-> provisioning unattended.
-
-Use the `SKIP_*` environment flags for a local or lean install. Each numbered
-script checks its flag and skips cleanly.
-
-| Flag | Skips |
-| --- | --- |
-| `SKIP_TELEGRAM` | The interactive BotFather token step. |
-| `SKIP_RUNTIME_REPO` | Creating the GitHub runtime repo. |
-| `SKIP_PLANE` | Creating a Plane project. |
-| `SKIP_BLOODBANK` | Installing the BloodBank consumer. |
-| `SKIP_SYSTEMD` | Installing `systemd` units (gateway, consumer, heartbeat timer). |
-
-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=linear
-```
-
-After provisioning, set the board binding in
-`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.
-
-`SKIP_SYSTEMD` gates the gateway, consumer, and the fused `heartbeat` timer in
-`70-systemd.sh`. The heartbeat timer is what drives the sentinel pass and the
-gated checkpoint, so a local install that wants the sentinel running must leave
-`SKIP_SYSTEMD` unset (or install the timer afterward).
-
-## Propagating changes
-
-The template is the single source of truth. Deployments pick up engine changes
-with `copier update`, which performs a three-way merge against the recorded
-answers in `.copier-answers.yml`. Local provisioning state, such as board ids
-and tokens, is preserved while the engine logic refreshes.
-
-```bash
-cd /path/to/your-project
-copier update ./agents/hermes/pm
-```
-
-<!-- prettier-ignore -->
-> [!NOTE]
-> `copier update` re-runs the `_tasks` chain. Pass the same `SKIP_*` flags you
-> used at provision time so the update doesn't try to recreate cloud resources.
-
-## History: consolidation into the PM heartbeat
-
-The sentinel began as a bespoke loop on the `pm` role, was briefly extracted into
-a standalone `scrum-master` role with its own `continuous-ticket-sentinel` timer,
-and has now been folded back into the unified PM. Today there is exactly one
-role (`pm`), one engine (under `.scripts/sentinel/`), and one timer
-(`hermes-<agent>-heartbeat.timer`) that fuses the board-reconciliation sentinel
-pass with a gated runtime checkpoint. The old per-agent
-`hermes-<agent>-continuous-ticket-sentinel.timer` and the separate
-`hermes-<agent>-checkpoint.timer` are gone; both are replaced by the single
-`heartbeat` timer. The earlier standalone-role design is recoverable from Git
-history if you ever need to compare.
-
-## Known gotchas
-
-These cost real debugging time. Watch for them.
-
-- **The interactive Telegram step.** `30-telegram.sh` uses `read` to capture a
-  bot token, so it blocks unattended runs. Always pass `SKIP_TELEGRAM=1` for
-  automated provisioning.
-- **The dispatcher needs Bash.** `ticket-provider.sh` reads
-  `${BASH_SOURCE[0]}`. Source it under `bash`, not `sh`. The adapters
-  themselves are POSIX shell.
-- **`emit-event.py` blocks on standard input.** When it runs in a
-  non-interactive context, it reads standard input for an optional JSON payload.
-  Redirect standard input from `/dev/null` when you call it from another script.
-  The enforcement scripts already do this.
-- **Brace defaults in `dash`.** Avoid `${2:-{}}` in adapter scripts. The `dash`
-  shell mis-parses the `{}` default and appends a stray brace. Hoist the default
-  into a variable instead.
-- **Quoting in `python3 -c`.** See the warning in
-  [Providers: adding a provider](providers.md#adding-a-provider).
-- **`flock` is Linux-only.** macOS doesn't ship `flock`, so the heartbeat runner
-  falls back to an atomic `mkdir` lock. Keep both paths working in the runner.
-- **Plane state is a bare UUID.** The Plane v1 API returns an issue's `state` as
-  a UUID with no embedded object, so the adapter must join issues against the
-  project's states map. Descriptions are `description_html`, not
-  `description_stripped`.
-
-## Open roadmap
-
-The following work is open for the incoming agent, roughly in priority order.
-
-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.
-2. **Confirm `install-local.sh` on a real macOS machine.** The Linux path is
-   verified end to end and the Plane adapter is verified live, but the macOS
-   `launchd` agent, the `mkdir` lock, and the assumption that the older Copier
-   steps (`10-hermes-profile.sh`, `80-registry.sh`) are Darwin-clean get their
-   first real run on a Mac.
-3. **Confirm the first full Hermes reconciliation pass on a fresh PM.** The
-   heartbeat, adapter, and enforcement layers are verified, but the first live
-   `run:full` pass with the rendered prompt on a newly provisioned PM is the
-   last thing to watch.
-
-## Read next
-
-- [Architecture](architecture.md): the engine internals.
-- [Providers](providers.md): the adapter contract and verification process.

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

@@ -1,203 +0,0 @@
-# Provider adapters
-
-This guide is the reference for the ticket-provider abstraction: the contract
-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.
-
-## The contract
-
-Each adapter is a standalone POSIX shell script under
-`template/.scripts/providers/<name>.sh`. It reads its credentials from the
-environment and its board binding from `role.yaml` under `ticket_provider`. It
-takes an operation as its first argument and writes JSON or a status string to
-standard output.
-
-The dispatcher, `template/.scripts/lib/ticket-provider.sh`, resolves the active
-provider and routes calls. Source it, then call `tp <operation> [args...]`:
-
-```bash
-. .scripts/lib/ticket-provider.sh
-tp active_milestone
-tp list_issues
-tp transition DEL-42 completed
-```
-
-Every adapter must implement these operations.
-
-| Operation | Arguments | Output |
-| --- | --- | --- |
-| `resolve` | none | JSON `{provider, board_id, board_url}`. Validates credentials and board binding. |
-| `active_milestone` | none | JSON `{id, name, state}` for the current milestone, cycle, or board. |
-| `list_issues` | none | JSON array of `{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 the new comment id. |
-| `transition` | `<id> <normalized-state>` | Moves the issue to a normalized state. |
-| `create_board` | `<name> <ident> <desc>` | JSON `{board_id, board_url}`. Creates or reuses the board. |
-
-The `transition` operation accepts only the normalized states from
-[Architecture: normalized states](architecture.md#normalized-states):
-`backlog`, `unstarted`, `started`, `in_review`, and `completed`. The adapter
-maps each to its back end's concrete state.
-
-## The adapters that ship today
-
-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
-  the v1 API returns an issue's `state` as a bare UUID with no `state_detail`,
-  so the adapter joins each issue against the project's states map; descriptions
-  come from `description_html`.
-- **Trello** (`providers/trello.sh`) uses the Trello REST API with `key` and
-  `token` query-parameter authentication. A board maps to both the project and
-  the milestone, a list maps to the state, and a card maps to the issue. It's
-  implemented but not yet verified against a live board.
-
-### Credentials and binding by provider
-
-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`. Endpoint: `PLANE_BASE` (default
-  `https://plane.delo.sh`).
-- Binding:
-
-  ```yaml
-  ticket_provider:
-    name: plane
-    workspace: <workspace-slug>
-    project: <project-uuid> # set by 42-ticket-provider.sh
-  ```
-
-</details>
-
-<details>
-<summary>Trello</summary>
-
-- Credentials: `TRELLO_KEY` and `TRELLO_TOKEN`.
-- Binding:
-
-  ```yaml
-  ticket_provider:
-    name: trello
-    board: <board-id> # set by 42-ticket-provider.sh
-    state_map: { backlog: "Backlog", started: "In Progress", completed: "Done" }
-  ```
-
-</details>
-
-## Adding a provider
-
-To add a fourth provider, for example GitHub Issues or Jira, follow these steps.
-
-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.
-3. Fail fast and clean. Validate credentials at the top of the script, before
-   any pipe, so a missing key prints one error line instead of a stack trace.
-   The existing adapters call a `need_key` helper for this.
-4. Add the provider to the `ticket_provider` question in `copier.yml` so it
-   appears as a choice.
-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 `linear`, `plane`, and `trello`
-   cases.
-7. Validate and verify with the steps below.
-
-<!-- prettier-ignore -->
-> [!WARNING]
-> Don't put escaped double quotes inside a single-quoted `python3 -c '...'`
-> block. A single-quoted shell string keeps backslashes literal, so `\"`
-> reaches Python as a backslash-quote and fails to parse. Use a `python3 -
-> <<'PY'` heredoc, or hoist values into variables, when you need quotes.
-
-## Validating an adapter offline
-
-Before you touch a live board, confirm the adapter parses and fails cleanly.
-
-1. Check shell syntax:
-
-   ```bash
-   sh -n template/.scripts/providers/<name>.sh
-   ```
-
-2. Check the inline Python blocks. Extract each `<<'PY'` heredoc and each
-   `python3 -c '...'` block and run it through `python3 -c "import ast;
-   ast.parse(open('block').read())"`, or use the small extraction script in
-   [Development guide: validating
-   locally](development.md#validating-changes-locally).
-
-3. Confirm a missing credential produces one clean error line and a non-zero
-   exit, with no Python traceback:
-
-   ```bash
-   ( unset LINEAR_API_KEY; sh template/.scripts/providers/linear.sh resolve )
-   ```
-
-## Verifying an adapter against a live board
-
-When you have credentials, exercise the read operations against a real board.
-The following pattern stages a minimal role directory and runs the adapter. It
-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 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/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.
-LIB="$RD/.scripts/lib/ticket-provider.sh"
-bash -c '. "$1"; tp resolve' _ "$LIB"
-bash -c '. "$1"; tp list_issues' _ "$LIB" | python3 -c 'import sys,json; print(len(json.load(sys.stdin)),"issues")'
-```
-
-To verify `transition` and `comment`, which modify the board, use a disposable
-test ticket. Don't run write operations against production tickets during
-verification.
-
-<!-- prettier-ignore -->
-> [!NOTE]
-> The dispatcher needs Bash because it reads `${BASH_SOURCE[0]}` to find the
-> providers directory. The adapters themselves are POSIX shell and run under
-> `sh`. Run the dispatcher with `bash -c`, as shown above, not `sh -c`.
-
-## Read next
-
-- [Development guide](development.md): the full edit, validate, and propagate
-  workflow, plus the open roadmap, which includes live-verifying Plane and
-  Trello.