@delorenj/pjangler 1.2.21 → 1.2.33

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

@@ -1,237 +0,0 @@
-# Operations
-
-Running the hermes fleet day-to-day: provisioning, starting, stopping, retiring,
-debugging.
-
-## Provision a new agent
-
-```bash
-cd /path/to/the/project-repo            # MUST be inside a git repo
-copier copy gh:delorenj/hermes-agent-template ./agents/hermes/<role> \
-  --data target_repo=<repo-name>        # REQUIRED — must match the parent repo name
-  --data role=<role>                    # pm | dev | review | ops | qa | ci | ...
-  --data agent_purpose="<one-liner>"
-  --data soul_tone=direct               # direct | playful | formal | terse
-  --trust
-```
-
-`target_repo` MUST be supplied explicitly. The template no longer derives it
-from `dst_path` (path-based regex was unreliable across relative vs absolute
-invocations).
-
-### What runs
-
-| Step | What happens | Skippable via |
-| --- | --- | --- |
-| 00 banner | Print identity | n/a |
-| 01 config | Seed `~/.config/hermes-agent-template/config.toml` from the shipped example if absent (see [Configuration](#configuration)) | n/a |
-| 05 fleet env | Ensure `~/.hermes/fleet.env` exists (shared Hermes binary/repo/registry source-of-truth), populated from `config.toml` | n/a |
-| 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` |
-| 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 |
-| 99 summary | Print summary | n/a |
-
-Every step is idempotent — re-running the entire provisioning is safe. Each
-step writes a `.done-NN-*` marker; delete that marker to force a re-run.
-
-## Configuration
-
-Environment-specific defaults are NOT hardcoded — they live in
-`~/.config/hermes-agent-template/config.toml` (override the path with
-`$HERMES_TEMPLATE_CONFIG`). Step `01 config` seeds it from the shipped
-`config.example.toml` on first run. Every provisioning script and the generated
-`hermes` launcher read it.
-
-Resolution precedence for each value: **explicit env var → `~/.hermes/fleet.env`
-→ `config.toml` → built-in fallback**. To retarget the whole template for a
-different machine/user, edit this one file:
-
-```toml
-[fleet]
-hermes_bin = "/path/to/hermes-agent/.venv/bin/hermes"
-hermes_repo = "/path/to/hermes-agent"
-oauth_file = "~/.hermes/auth.json"
-codex_home = "~/.codex"
-canonical_skills_dir = "/path/to/.agents/skills"
-voxxy_plugin_dir = "~/code/voxxy/plugins/tts/voxxy"
-vox_url = "https://vox.delo.sh"
-
-[github]
-runtime_repo_owner = "your-gh-owner"
-
-[plane]
-base = "https://plane.example.com"
-workspace = "your-workspace"
-
-[bloodbank]
-nats_host = "127.0.0.1"
-nats_port = 4222
-```
-
-`role.yaml` stores an empty `runtime.github_owner` and `plane.workspace` for
-freshly provisioned agents; the shell layer fills them from `config.toml` at
-runtime (older manifests that baked `owner/name` into `runtime.github_repo`
-still work unchanged).
-
-## Fleet source-of-truth
-
-`~/.hermes/fleet.env` is the single shared pointer every generated launcher reads:
-
-- `HERMES_FLEET_BIN` (the exact Hermes executable all agents use)
-- `HERMES_FLEET_REPO` (the upstream/fork checkout you keep on the edge)
-- `HERMES_FLEET_REGISTRY_FILE` (defaults to `~/.hermes/agents-registry.yaml`)
-- `HERMES_FLEET_OAUTH_FILE` (shared Hermes provider OAuth store)
-- `HERMES_FLEET_CODEX_HOME` (shared Codex CLI/app-server auth/config home)
-
-If you `git pull`/sync the repo at `HERMES_FLEET_REPO` and rebuild/update that
-same binary path, every wrapper benefits immediately with no per-agent edits.
-For Codex auth, run `hermes auth add openai-codex` through any generated agent
-launcher once; all agents using the same fleet env read the same Hermes OAuth
-store afterward.
-
-To retrofit older provisioned agents onto this model, run:
-
-```bash
-cd /home/delorenj/code/hermes-agent-template
-./scripts/backfill-fleet-sot.sh
-```
-
-## Start the daemons for an agent
-
-```bash
-AGENT=bloodbank-pm
-systemctl --user start hermes-${AGENT}-consumer.service
-systemctl --user start hermes-${AGENT}-heartbeat.timer
-
-# Gateway will fail to start until Telegram is wired up (no other platforms
-# configured). After running .scripts/30-telegram.sh:
-systemctl --user start hermes-${AGENT}-gateway.service
-```
-
-## Talk to an agent
-
-| Channel | How |
-| --- | --- |
-| Telegram | DM `@<repo>_<role>_bot` (once Telegram is wired) |
-| Local CLI | `./agents/hermes/<role>/hermes chat "..."` |
-| Bloodbank | Publish to `bloodbank.cmd.v1.agent.task.assign` with `data.target_agent_id = <agent_id>` |
-
-## Inspect fleet state
-
-```bash
-python3 - <<'EOF'
-import yaml, pathlib
-agents = yaml.safe_load(pathlib.Path.home().joinpath('.hermes/agents-registry.yaml').read_text())['agents']
-for k, v in agents.items():
-    print(f"{k:25s}  @{v['telegram']['bot_username']:30s}  plane={v['plane']['identifier']}  runtime=gh:{v['runtime_repo']}")
-EOF
-
-# Service status
-systemctl --user list-units --state=active 'hermes-*'
-systemctl --user list-timers 'hermes-*'
-
-# Tail the consumer for live bloodbank events
-journalctl --user -fu hermes-<agent-id>-consumer.service
-```
-
-## Deferred manual steps (one-time per agent)
-
-### Telegram bot
-
-1. Open Telegram, message `@BotFather`
-2. `/newbot`, display name `<Repo> <ROLE>`, username `<repo>_<role>_bot`
-3. Copy the HTTP API token
-4. `/setjoingroups Disable`, `/setprivacy Disable`
-5. Re-run the wire-up step:
-   ```bash
-   cd <project>/agents/hermes/<role>
-   rm .scripts/.done-30-telegram
-   SKIP_TELEGRAM=0 ./.scripts/30-telegram.sh
-   systemctl --user restart hermes-<agent-id>-gateway.service
-   ```
-
-## Restore an agent on a new machine
-
-```bash
-cd /path/to/the/project-repo
-git submodule update --init --recursive
-git -C agents/hermes/<role>/runtime lfs pull
-
-# Restore secrets that were excluded from git:
-op read 'op://DeLoSecrets/agent-hm-<repo>-<role>/.env' > agents/hermes/<role>/runtime/.env
-# (or copy from a backup machine)
-
-# Symlink the profile dir
-ln -sfn $PWD/agents/hermes/<role>/runtime ~/.hermes/profiles/<repo>-<role>
-
-# Re-enable systemd units
-systemctl --user enable hermes-<repo>-<role>-{gateway,consumer}.service
-systemctl --user enable hermes-<repo>-<role>-heartbeat.timer
-systemctl --user start  hermes-<repo>-<role>-{consumer}.service
-systemctl --user start  hermes-<repo>-<role>-heartbeat.timer
-```
-
-## Retire an agent (manual, until v1.1 ships retire.sh)
-
-```bash
-AGENT=bloodbank-dev
-# 1. Stop daemons
-systemctl --user disable --now hermes-${AGENT}-{gateway,consumer}.service
-systemctl --user disable --now hermes-${AGENT}-heartbeat.timer
-
-# 2. Delete hermes profile (cascades to symlinked runtime — make sure
-#    that's what you want!)
-hermes profile delete ${AGENT}
-
-# 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_33GOD_API_KEY}"
-
-# 4. BotFather: /deletebot @<repo>_<role>_bot
-# 5. Archive runtime repo (GitHub UI; we don't have delete_repo scope by default)
-# 6. Remove registry entry
-python3 -c "
-import yaml, pathlib
-p = pathlib.Path.home() / '.hermes' / 'agents-registry.yaml'
-d = yaml.safe_load(p.read_text()); d['agents'].pop('${AGENT}', None)
-p.write_text(yaml.safe_dump(d))"
-
-# 7. In the project repo, remove the submodule
-cd /path/to/project
-git submodule deinit -f agents/hermes/<role>/runtime
-git rm -f agents/hermes/<role>/runtime
-rm -rf .git/modules/agents/hermes/<role>/runtime
-rm -rf agents/hermes/<role>
-```
-
-## Troubleshooting
-
-### Gateway service fails immediately
-- Check `~/.hermes/profiles/<agent>/.env` has `TELEGRAM_BOT_TOKEN` set
-- `journalctl --user -u hermes-<agent>-gateway.service`
-- If "all configured messaging platforms failed to connect" — Telegram step wasn't run yet. Run `.scripts/30-telegram.sh` first.
-
-### 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 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
-sentinel pass), gated to at most once an hour.
-- Look at the most recent heartbeat log: `tail <role>/runtime/logs/heartbeat.log`
-- Verify the submodule's git remote is reachable: `cd ...runtime && git push origin HEAD`
-- If LFS items fail to push: `git lfs push origin HEAD --all`
-- Force a checkpoint out-of-band: `bash agents/hermes/<role>/.scripts/checkpoint.sh`
-
-### Profile dir contains nested `profiles/profiles/...`
-- That was a `--clone-all` bug; we switched to `--clone`. If you see it, just `rm -rf` the nested tree. The template's 10-hermes-profile.sh also has a belt-and-suspenders rm.
-
-### `hermes` launcher complains about HERMES_BIN
-- Check the launcher script: `./agents/hermes/<role>/hermes` falls back to `$HOME/.hermes/hermes-agent/.venv/bin/hermes` (after `$HERMES_BIN`, `fleet.env`, and config.toml). Override with `HERMES_BIN=/path/to/hermes ./agents/hermes/pm/hermes status`.

package/templates/hermes-agent/docs/runbooks/runtime-checkpoint-repair.md

@@ -1,171 +0,0 @@
-# Runbook: repair a failing runtime-checkpoint service
-
-Status: Active operations runbook
-Applies to: every Hermes agent whose `runtime/` is a git submodule checkpointed
-by its `hermes-<agent>-heartbeat.service` systemd unit (the heartbeat runner
-calls `.scripts/checkpoint.sh` to commit+push the runtime).
-
-This runbook fixes the failure where the runtime checkpoint dies with
-**exit 128** and the agent's runtime "brain" stops being backed up. The
-checkpoint now runs inside the fused heartbeat tick (board-reconciliation
-sentinel pass + gated checkpoint), so the failing unit is the agent's
-`heartbeat.service`. It is written so any agent or operator can copy it to
-another repo and apply it safely. First captured 2026-06-01 fixing the
-Drumjangler PM checkpoint; the same fault was present on other agents in the
-fleet.
-
-## Symptom
-
-```bash
-systemctl --user status hermes-<agent>-heartbeat.service
-#   Active: failed (Result: exit-code) ... status=128/n/a
-#   the heartbeat invokes .../agents/hermes/<role>/.scripts/checkpoint.sh
-```
-
-`checkpoint.sh` is just `cd runtime && git add -A && commit && push`. Run it by
-hand and you see the real error:
-
-```text
-fatal: in unpopulated submodule 'agents/hermes/<role>/runtime'
-```
-
-## Root cause
-
-`agents/hermes/<role>/runtime` is registered as a **git submodule** in the
-project repo (`.gitmodules` has its URL; the parent index holds a `160000`
-gitlink), **but the submodule is not populated** — there is no `runtime/.git`,
-and `.git/modules/<path>` is gone. So any git command run *inside* `runtime/`
-resolves **up to the parent repo**, which treats `runtime/` as an unpopulated
-submodule path and makes `git add -A` fatal (exit 128).
-
-Confirm it:
-
-```bash
-RT=agents/hermes/<role>/runtime
-git -C "$RT" rev-parse --show-toplevel     # prints the PARENT repo, not RT  -> red flag
-ls "$RT/.git"                               # missing  -> unpopulated
-git ls-files -s "$RT" | head -1             # mode 160000 <sha> ...           -> gitlink
-git config -f .gitmodules --get-regexp "$RT" # submodule.<path>.url git@...
-ls .git/modules/"$RT" 2>/dev/null || echo "objects gone -> must re-fetch from remote"
-```
-
-Consequence: the agent's durable brain (`SOUL.md`, `memories/`, `profiles/`,
-`skills/`, config) lives on disk (the running agent still reads it) but is **not
-committed or pushed anywhere** — no backup until this is repaired.
-
-## The fix (safe, in-place, preserves all on-disk state)
-
-The key safety property: `git reset --mixed` moves `HEAD` + the index only and
-**never rewrites working-tree files**, so the live brain (and a multi-hundred-MB
-`state.db`) is untouched. Never use `git submodule update`/`git checkout <tree>`
-here — those would overwrite live, uncommitted edits with the older committed
-versions.
-
-```bash
-RT=agents/hermes/<role>/runtime
-URL=$(git config -f .gitmodules --get submodule."$RT".url)
-
-# 0. remote must be reachable (read-only)
-GIT_SSH_COMMAND='ssh -o BatchMode=yes -o ConnectTimeout=15' git ls-remote "$URL" >/dev/null
-
-cd "$RT"
-# 1. re-init git in place on branch 'main' (creates .git/ only; no file changes)
-git init -q
-git symbolic-ref HEAD refs/heads/main
-git remote add origin "$URL"
-git fetch -q origin
-# 2. re-base history onto the remote tip WITHOUT touching the working tree
-git reset --mixed -q origin/main
-git branch --set-upstream-to=origin/main main 2>/dev/null || true
-# 3. the repo uses git-lfs for *.db/images (.gitattributes); register filters
-git lfs install --local
-# 4. restore tracked config that may be missing on disk (avoids spurious deletes)
-git checkout origin/main -- .gitattributes README.md 2>/dev/null || true
-```
-
-### Make it sustainable: back up the brain, not volatile state
-
-Even though `.gitattributes` routes `*.db` through LFS, committing a live,
-constantly-growing `state.db` (often hundreds of MB) every hour is not
-sustainable, and `lsp/` (node_modules), `checkpoints/` (a nested object store),
-and `sessions/` (ephemeral dumps) must never be committed. The checkpoint repo's
-job is the **durable brain**. Ensure `runtime/.gitignore` contains:
-
-```gitignore
-# Runtime working state — NOT part of the durable brain backup.
-*.db
-*.db-wal
-*.db-shm
-*.sqlite
-*.sqlite3
-*.lock
-.update_check
-lsp/
-checkpoints/
-sessions/
-cron/
-*_cache.json
-```
-
-Then untrack anything volatile that is currently tracked (keeps the files on
-disk):
-
-```bash
-git rm -r --cached --ignore-unmatch state.db state.db-wal state.db-shm cron
-```
-
-### Verify BEFORE committing (mandatory safety gate)
-
-```bash
-git add -A --dry-run | awk '{print $2}' | while read -r f; do
-  [ -f "$f" ] && s=$(stat -c%s "$f") && [ "$s" -gt 1048576 ] && echo "BIG: $((s/1048576))MB $f"; done
-# ^ must print nothing. Also confirm no state.db / lsp/ / sessions/ / checkpoints/,
-#   and no secrets (.env, auth.json, *.key, *token*) in the staged set.
-```
-
-### Commit, push, and bring the service green
-
-```bash
-bash agents/hermes/<role>/.scripts/checkpoint.sh        # exits 0, pushes brain
-systemctl --user reset-failed hermes-<agent>-heartbeat.service
-systemctl --user start       hermes-<agent>-heartbeat.service
-systemctl --user show hermes-<agent>-heartbeat.service -p Result -p ExecMainStatus
-#   Result=success  ExecMainStatus=0
-```
-
-## One-shot
-
-`scripts/repair-runtime-checkpoint.sh` automates all of the above. It is
-**dry-run by default** (diagnoses and prints the plan) and only mutates with
-`--apply`. Run it from a project repo root:
-
-```bash
-# diagnose
-hermes-agent-template/scripts/repair-runtime-checkpoint.sh agents/hermes/pm/runtime
-# apply the in-place re-attach + .gitignore policy + untrack (no commit)
-hermes-agent-template/scripts/repair-runtime-checkpoint.sh --apply agents/hermes/pm/runtime
-# then validate the service
-systemctl --user reset-failed <svc> && systemctl --user start <svc>
-```
-
-## Fleet sweep — this is rarely just one repo
-
-```bash
-systemctl --user list-units --all '*-heartbeat.service' | grep -i failed
-# for each failing agent, locate its runtime and run the repair script.
-```
-
-## Lessons learned (why this happened / what to remember)
-
-- An **unpopulated submodule** silently redirects in-directory git commands to
-  the parent repo; `git add -A` then fatals with exit 128. The fix is to restore
-  the submodule's own `.git` (objects from the remote), not to touch the parent.
-- `git reset --mixed <ref>` is the safe way to re-attach history to a populated
-  working directory: it preserves every on-disk file.
-- The checkpoint must **exclude volatile working state** (`state.db*`, `lsp/`,
-  `checkpoints/`, `sessions/`, caches, locks). Back up identity + memory + skills.
-- Core dumps from the agent will **not** appear in `coredumpctl`/`/var/crash` on
-  Ubuntu: apport discards crashes from unpackaged venv-Python binaries. Use
-  `PYTHONFAULTHANDLER=1` or a private `core_pattern` to capture a backtrace.
-- Always run the fleet sweep — provisioning copies this layout to every agent,
-  so a structural fault tends to be fleet-wide.

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

@@ -1,119 +0,0 @@
-# Heartbeat sentinel — developer handoff
-
-This guide is the entry point for continuing development of the **PM's heartbeat
-sentinel**: a provider-agnostic, always-on ticket-reconciliation engine with an
-autonomous adversarial review (act, do not wait). It is owned by the unified
-`pm` role and runs out-of-band on the PM's heartbeat timer. Read this first,
-then follow the links to the deeper guides. It's written so a Hermes agent (or a
-human) can pick up the work without prior context.
-
-## What the heartbeat sentinel is
-
-The sentinel is the PM's continuous board-reconciliation loop, and its job is to
-keep a project moving: it makes sure exactly one implementation worker is
-advancing a ready ticket, or it records why none can. When a ticket reaches the
-review lane, it runs an independent, rigorous **adversarial review** and acts on
-the verdict autonomously — never parking work to wait on the operator. If the
-work hasn't drifted from the operator's locked intent and clears the gate, the
-review is `accepted`: the loop treats the ticket as done, unblocks dependents,
-and emits a decision event. A real finding is `held` and the ticket goes back to
-active.
-
-There is no longer a separate `scrum-master` role; the sentinel folded into the
-PM and now runs as part of the PM's **heartbeat** — a fused systemd-timer tick
-that does the board-reconciliation pass and then a gated runtime checkpoint
-(`.scripts/heartbeat.sh`). The engine itself lives under the PM at
-`.scripts/sentinel/`.
-
-It talks to the ticket board through a pluggable adapter, so the same engine
-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`.
-
-## Status at handoff
-
-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).
-- The **Trello** adapter is implemented against the same contract but is
-  **not** yet verified against a live board.
-- The heartbeat runner uses `flock` on Linux and an atomic `mkdir` lock on macOS
-  so concurrent ticks never overlap. The systemd timer (Linux) is the primary
-  scheduler; a `launchd` agent covers macOS.
-
-## Quick local install
-
-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_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
-```
-
-It installs `hermes` and `copier` if missing, writes a host-correct local
-config, provisions the `pm` role, binds the PM to an existing board, and
-installs the PM's heartbeat timer (`systemd` on Linux, `launchd` agent on
-macOS). See [Development guide: local install](development.md#local-install-one-command).
-
-<!-- prettier-ignore -->
-> [!IMPORTANT]
-> Full (non-local) provisioning is outward-facing. It can create a GitHub
-> 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
-> installs.
-
-## Where the pieces live
-
-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 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/{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). |
-| `template/.scripts/heartbeat.sh` | The heartbeat runner: the sentinel full-pass dispatch (with its own cooldown/lock) plus the gated runtime checkpoint, fused into one tick. |
-| `template/.scripts/sentinel.prompt.md.jinja` | The prompt the runner feeds to Hermes for a full reconciliation pass (rendered to `.scripts/sentinel.prompt.md`). |
-| `template/.scripts/sentinel/bin/` | Enforcement tools: `issue-autonomous-review.sh`, `issue-close-gate.sh`, `emit-event.py`. |
-| `template/.scripts/sentinel/docs/` | Runtime protocol docs shipped to each deployment. |
-
-The `docs/sentinel/` directory you're reading now holds the **developer**
-docs for this template. The `template/.scripts/sentinel/docs/` directory
-holds the **runtime** protocol docs that ship into each provisioned project for
-the agent to read at run time. Keep the two in sync when behavior changes.
-
-## Read next
-
-- [Architecture](architecture.md): how the engine, the adapter contract, the
-  normalized states, and the autonomous adversarial review fit together.
-- [Providers](providers.md): the adapter contract reference and a step-by-step
-  guide to adding or verifying a provider.
-- [Development guide](development.md): the edit, validate, and propagate
-  workflow; provisioning and its `SKIP_*` flags; known gotchas; and the open
-  roadmap.
-
-## Next steps for the incoming agent
-
-The highest-value open work, in order:
-
-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
-   their first real run on a Mac.
-3. Confirm the first full Hermes reconciliation pass on a freshly provisioned PM
-   reconciles the board cleanly.