@delorenj/pjangler 1.2.25 → 1.2.33

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

@@ -1,140 +0,0 @@
----
-stepsCompleted: [1]
-inputDocuments:
-  - docs/architecture.md
-  - docs/operations.md
-  - README.md
-  - /home/delorenj/code/pjangler/src/commands/hermes/RunCopierTemplate.ts
-  - /home/delorenj/code/pjangler/src/parity/index.ts
-  - /home/delorenj/.hermes/agents-registry.yaml
-workflowType: prd
-project_name: Fleet Control Plane
-date: 2026-06-27
-status: draft-ready
----
-
-# Fleet Control Plane PRD
-
-## Problem
-
-The Fleet is composed of valuable independent repos and runtime surfaces, but
-the binding contract between them is implicit and drifting.
-
-Current symptoms include:
-
-- `pjangler` is already the de facto control plane, but its role is not stated
-  as an architectural contract.
-- `pjangler/templates/hermes-agent` can carry dirty vendored template changes
-  that differ from `~/code/hermes-agent-template`.
-- The live fleet uses checkpoint timers while newer dirty template work points
-  toward heartbeat timers.
-- The registry, profiles, fleet env, systemd units, and role manifests can
-  disagree without one authoritative reconciliation path.
-- n8n is a promising visual orchestration layer, but should not become another
-  competing source of truth.
-
-## Product Goal
-
-Make `pjangler` the explicit Fleet control plane and introduce a versioned Fleet
-contract that lets the independent parts stay independent while making their
-runtime coupling visible, validated, and repairable.
-
-## Users
-
-- Primary operator: Deloren, managing a personal but production-like fleet.
-- Agent implementers: Codex, Hermes PM agents, and future worker agents acting
-  from explicit contracts.
-- Visual orchestrator: n8n workflows that coordinate Fleet health, delegation,
-  and reconciliation.
-
-## Functional Requirements
-
-FR1: The system shall define a versioned Fleet contract that records template
-source versions, service model, schema versions, and supported runtime modes.
-
-FR2: `pjangler` shall expose `pj templates status` to report each vendored
-template source, commit, tag, dirty state, and effective provisioning source.
-
-FR3: `pjangler` shall expose `pj fleet status` to compare the Fleet contract
-against `~/.hermes/fleet.env`, `~/.hermes/agents-registry.yaml`, profiles,
-role manifests, runtime repos, and systemd units.
-
-FR4: `pjangler` shall expose `pj fleet reconcile` with dry-run by default and
-explicit `--apply` mutation mode.
-
-FR5: The Fleet registry shall support managed exceptions through fields such as
-`managed`, `kind`, `owner`, `source`, and `notes`.
-
-FR6: The implementation shall validate `.project.json`, `role.yaml`,
-`agents-registry.yaml`, `profile.yaml`, and `fleet-contract.yaml` with explicit
-schemas.
-
-FR7: `pjangler` publishing shall fail when vendored template submodules are
-dirty, mismatched, or missing required files.
-
-FR8: The heartbeat v2 strategy shall use n8n as the visual orchestration plane
-and systemd as the local survival fallback.
-
-FR9: n8n workflows shall read Fleet state from `pjangler`/Fleet registry rather
-than storing independent Fleet truth.
-
-FR10: n8n workflow generation shall be reproducible from `pjangler` and must be
-validatable before creation or update.
-
-FR11: The implementation shall repair known current drift, including stale
-runtime scaffold fallback paths, heartbeat/checkpoint mismatch, stale registry
-Hermes paths, and invalid generated role model fields.
-
-FR12: The operator shall be able to inspect and run all checks locally without
-network side effects unless an apply or create flag is explicitly provided.
-
-## Non-Functional Requirements
-
-NFR1: Default commands must be read-only or dry-run.
-
-NFR2: Reconciliation must never destroy or merge runtime state automatically
-when profiles or runtime repos contain ambiguous data.
-
-NFR3: n8n outage must not prevent baseline agent health, profile gateway
-operation, fleet Bloodbank routing, or runtime checkpoint fallback.
-
-NFR4: Validation output must be deterministic and grep-friendly.
-
-NFR5: Release gates must be suitable for local CLI use and npm `prepublishOnly`.
-
-NFR6: Secrets must remain outside committed artifacts and generated workflow
-definitions.
-
-NFR7: The architecture must support fast solo iteration without requiring a
-large platform migration before useful checks land.
-
-NFR8: Generated n8n workflow code must follow n8n workflow SDK design guidance:
-normalize data early, avoid accidental per-item fanout, and validate workflow
-code before creation.
-
-## Scope
-
-In scope:
-
-- Fleet contract design.
-- `pjangler` status, reconcile, validation, and release gates.
-- n8n workflow generation artifacts and first supervisor workflow path.
-- Systemd fallback heartbeat/checkpoint strategy.
-- Current drift repair stories.
-
-Out of scope for the first implementation:
-
-- Rewriting Hermes internals beyond the minimal profile/config validation needed.
-- Migrating every agent to custom n8n nodes.
-- Removing systemd.
-- Making n8n the Fleet source of truth.
-
-## Success Criteria
-
-- `pj templates status` clearly explains which template bytes will be used.
-- `pj fleet status` reports registry/profile/systemd/schema drift without
-  destructive changes.
-- `pj fleet reconcile --apply` fixes safe drift and labels unsafe drift manual.
-- `npm run prepublishOnly` fails if vendored templates are dirty.
-- A generated n8n Fleet supervisor workflow can be validated before creation.
-- Agents continue local fallback behavior when n8n is unavailable.

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

@@ -1,335 +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 local runtime | Populate missing files from role-local `.runtime-scaffold/` into ignored `./runtime/`, symlink `~/.hermes/profiles/<id>` → runtime, and refuse stale project gitlinks/mappings; PM roles also link the Voxxy plugin and set `tts.provider: voxxy` | `SKIP_RUNTIME_REPO=1` |
-| 30 telegram | Verify an invocation-supplied, profile-dedicated BotFather token; reject fleet reuse; write only to runtime/.env | `SKIP_TELEGRAM=1` |
-| 31 slack | Disabled/deferred by default; verify a dedicated app+bot pair with `auth.test` and write it only to runtime/.env when explicitly enabled | `SKIP_SLACK=1` |
-| 40 plane | Create Plane project in 33god workspace (1:1 with agent), patch identifier into role.yaml | `SKIP_PLANE=1` |
-| 60 bloodbank | Compatibility checkpoint for fleet-shared routing; installs no files, dependencies, or services | `SKIP_BLOODBANK=1` remains a no-op |
-| 70 systemd | Install user units: profile gateway and board-reconciliation heartbeat timer | `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"
-hermes_git_url = "https://github.com/delorenj/hermes-agent.git"
-hermes_git_ref = "feature/PJAN-19-routing-publication"
-hermes_git_sha = "113e1b182b6d72a7dd02a191f134a41668ceaf0e"
-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"
-
-[plane]
-base = "https://plane.example.com"
-workspace = "your-workspace"
-```
-
-`role.yaml` stores compatibility metadata for older generated roles, but the
-current local-runtime provisioner does not use it for storage. Plane workspace
-defaults are still filled from `config.toml`.
-
-## 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.
-
-The reviewed runtime source is the `delorenj/hermes-agent` fork, publication
-ref `feature/PJAN-19-routing-publication`, pinned at
-`113e1b182b6d72a7dd02a191f134a41668ceaf0e`. `install-local.sh` performs a
-single-branch clone, verifies the pin is on that ref, passes both `--branch` and
-`--commit` to the checked-out installer, and refuses an existing checkout with
-a different origin. It never fetches or writes upstream `main`.
-
-To retrofit older provisioned agents onto this model, run:
-
-```bash
-cd /home/delorenj/code/hermes-agent-template
-./scripts/backfill-fleet-sot.sh
-```
-
-Then audit legacy consumers before relying on the fleet-shared Bloodbank
-gateway:
-
-```bash
-./scripts/fleet-sync.sh
-./scripts/fleet-sync.sh --apply
-```
-
-Any active, enabled, installed, or registry-declared
-`hermes-<agent>-consumer.service` is unhealthy drift. Apply mode disables and
-stops it, proves the unit is explicitly `inactive` and `disabled`, then removes
-the unit, reloads user systemd, and removes the legacy registry metadata. A
-user-manager/query error, failed disable, or ambiguous post-disable state fails
-closed and preserves both the unit file and registry metadata. The same cleanup
-runs in step 70 before its done marker is honored.
-
-Fleet registry and chat identity changes share `${registry_file}.lock`. `flock`
-owns the lock in the kernel (an on-disk lock file surviving a crash is safe),
-while atomic replace prevents partial YAML. Registry and lock files are mode
-`0600`; symlink targets are refused. Registry and profile-local credential
-replacements also sync the containing directory where the platform supports it.
-Unexpected directory-sync errors are reported as failures without marking the
-step complete, so rerunning the idempotent provisioning step is safe.
-
-## Start the daemons for an agent
-
-```bash
-AGENT=bloodbank-pm
-systemctl --user start hermes-${AGENT}-heartbeat.timer
-
-# Gateway will fail to start until at least one messaging platform is wired.
-# After running .scripts/30-telegram.sh or .scripts/31-slack.sh:
-systemctl --user start hermes-${AGENT}-gateway.service
-```
-
-## Talk to an agent
-
-| Channel | How |
-| --- | --- |
-| Telegram | DM `@<repo>_<role>_bot` (once Telegram is wired) |
-| Slack | DM or mention the verified per-agent Slack bot (once Slack is wired) |
-| Local CLI | `./agents/hermes/<role>/hermes chat "..."` |
-| Bloodbank | Publish to `bloodbank.cmd.v1.agent.invocation.start` 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-*'
-
-# Bloodbank routing identity consumed by the fleet-shared gateway
-python3 -c "import yaml,pathlib; print(yaml.safe_load(pathlib.Path.home().joinpath('.hermes/agents-registry.yaml').read_text())['agents']['<agent-id>']['bloodbank'])"
-```
-
-## 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
-   TELEGRAM_BOT_TOKEN='<bot-id>:<secret>' \
-     TELEGRAM_ALLOWED_USERS='<your-user-id>' \
-     SKIP_TELEGRAM=0 ./.scripts/30-telegram.sh
-   systemctl --user restart hermes-<agent-id>-gateway.service
-   ```
-
-The token is captured before shared fleet configuration is loaded, verified
-through Telegram `getMe`, checked against local token and bot-identity owners,
-and atomically written only to the profile's gitignored `runtime/.env` with
-mode `0600`. `~/.hermes/fleet.env` and `~/.hermes/.env` must not contain
-`TELEGRAM_BOT_TOKEN`; the manifest and registry store only verified bot
-identity metadata. `TELEGRAM_ALLOWED_USERS` is non-secret and may be shared.
-
-### Slack app and bot (opt-in)
-
-Slack remains deferred unless `ENABLE_SLACK=1` (also accepts
-`WIRE_SLACK=1`) is set or both credentials are supplied. Each enabled agent
-must have its own Slack app-level Socket Mode token and bot token; neither may
-be reused by another profile.
-
-```bash
-cd <project>/agents/hermes/<role>
-ENABLE_SLACK=1 \
-  SLACK_BOT_TOKEN='xoxb-...' \
-  SLACK_APP_TOKEN='xapp-...' \
-  SLACK_ALLOWED_USERS='U01ABC2DEF3' \
-  ./.scripts/31-slack.sh
-systemctl --user restart hermes-<agent-id>-gateway.service
-```
-
-The step calls Slack's read-only `auth.test` endpoint for the bot token, checks
-the local fleet for token or bot-identity reuse, and records only the verified
-workspace/bot identity in `role.yaml` and the fleet registry. Tokens are
-atomically written to the agent's gitignored `runtime/.env` with mode `0600`.
-They must never be placed in `~/.hermes/.env` or `~/.hermes/fleet.env`.
-
-`SLACK_ALLOWED_USERS` is non-secret and may instead be set in `fleet.env` as a
-shared policy. An empty allow-list is safe but denies all inbound Slack users.
-
-## Back up and restore an agent
-
-The template does **not** ship automatic backup for the ignored
-`agents/hermes/<role>/runtime/` directory. A project clone recreates the
-tracked role and its empty scaffold, not accumulated local state. Configure an
-encrypted filesystem backup or snapshot that includes the exact runtime path
-before treating the agent as recoverable.
-
-For a manual transfer, create a private archive, copy it to operator-managed
-encrypted storage, and verify both the checksum and readable member list:
-
-```bash
-PROJECT=/absolute/path/to/project
-ROLE=pm
-BACKUP_DIR="$HOME/.local/state/hermes-runtime-backups"
-mkdir -p -m 0700 "$BACKUP_DIR"
-BACKUP="$BACKUP_DIR/$(basename "$PROJECT")-${ROLE}-$(date -u +%Y%m%dT%H%M%SZ).tar.gz"
-tar -C "$PROJECT" -czf "$BACKUP" "agents/hermes/${ROLE}/runtime"
-chmod 0600 "$BACKUP"
-sha256sum "$BACKUP" > "${BACKUP}.sha256"
-sha256sum -c "${BACKUP}.sha256"
-tar -tzf "$BACKUP" >/dev/null
-```
-
-That archive may contain credentials and private conversations. It is not an
-off-host backup until it has been copied to encrypted storage controlled by the
-operator and independently verified there.
-
-Recovery sources are intentionally distinct:
-
-- The verified filesystem backup is the only complete source for local config,
-  sessions, databases, skills, and other runtime files.
-- Hindsight can restore only memories/events that were previously written to
-  its remote bank. It is not a backup of the runtime directory.
-- The secret manager can restore only credentials deliberately stored there;
-  it does not contain memories, sessions, or local configuration by default.
-- Re-running provisioning restores the scaffold and service definitions, not
-  learned state.
-
-Restore the project and provision the role first. With its services stopped,
-extract the verified archive at the project root, confirm the profile symlink
-targets the restored runtime, then enable the services.
-
-## Retire an agent (preserves runtime by default)
-
-Retirement stops external behavior and detaches the profile while preserving
-the role directory and every runtime byte. Do not use a profile command whose
-deletion behavior is unknown.
-
-```bash
-PROJECT=/absolute/path/to/project
-ROLE=pm
-AGENT=bloodbank-pm
-RUNTIME="$PROJECT/agents/hermes/$ROLE/runtime"
-PROFILE="$HOME/.hermes/profiles/$AGENT"
-
-systemctl --user disable --now "hermes-${AGENT}-gateway.service"
-systemctl --user disable --now "hermes-${AGENT}-heartbeat.timer"
-
-# Detach only the expected symlink. Never follow it into the runtime.
-test -L "$PROFILE"
-test "$(readlink -f -- "$PROFILE")" = "$(readlink -f -- "$RUNTIME")"
-unlink -- "$PROFILE"
-
-# Archive the Plane project and retire Telegram/Slack identities through their
-# administrative UIs, then remove the fleet registry entry under its lock.
-# The runtime directory remains in place.
-test -d "$RUNTIME"
-```
-
-### Runtime retention after retirement
-
-Profile and service retirement always preserves the local runtime. This
-release intentionally provides no automated runtime purge, and this operations
-guide supplies no deletion recipe.
-
-Any purge is a separate future operator-retention process. It requires a
-separately reviewed, path-safe tool that canonicalizes both the repository root
-and role path, refuses ambiguous or linked targets, and verifies that the
-backup archive contains the expected runtime members before it can remove any
-data. Until such a tool is reviewed and shipped, preserve the runtime.
-
-Removing the tracked role scaffold is a different project change and is not
-part of profile or service retirement.
-
-## 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.
-
-### Bloodbank command not reaching an agent
-- Confirm the fleet registry entry has `bloodbank.gateway_scope: fleet`
-- Confirm its `bloodbank.target_agent_id` exactly matches the command's
-  `data.target_agent_id`
-- Inspect the fleet-shared Bloodbank gateway; there is intentionally no
-  `hermes-<agent>-consumer.service` or runtime inbox to repair
-
-### Runtime changes are not appearing in Hindsight or backups
-
-Pure-local runtime changes are not synchronized by the heartbeat.
-- Look at the most recent heartbeat log: `tail <role>/runtime/logs/heartbeat.log`
-- Verify the configured filesystem backup includes the exact runtime path and
-  successfully restore-test its latest snapshot.
-- Query Hindsight separately for the agent bank; only events already written
-  there are recoverable from Hindsight.
-- Check the secret manager separately for the profile credentials you chose to
-  store there.
-
-### Profile dir contains nested `profiles/profiles/...`
-- That was a `--clone-all` bug; current provisioning uses `--clone`. Preserve
-  the profile and runtime, inspect the unexpected nesting, and move only the
-  confirmed redundant entries to a quarantine directory for review.
-
-### `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,31 +0,0 @@
-# Historical runbook: retired checkpoint architecture
-
-Status: Historical evidence only — **do not execute**
-
-This page formerly described recovery for an older per-agent persistence
-design. That design is not the current Hermes template contract, and its
-commands have intentionally been removed so an operator cannot mistake them
-for a supported repair procedure.
-
-Current agents use an ignored, pure-local
-`agents/hermes/<role>/runtime/` directory. Provisioning refuses stale project
-gitlinks or mappings at that exact path and preserves all existing runtime
-bytes. The heartbeat performs board reconciliation; it is not the runtime
-backup mechanism.
-
-For current recovery and retirement procedures, use
-[Operations](../operations.md#back-up-and-restore-an-agent). In particular:
-
-- configure and verify an encrypted filesystem backup for the exact runtime
-  path;
-- treat Hindsight as recovery for only the memories/events previously written
-  to its bank;
-- treat the secret manager as recovery for only credentials deliberately
-  stored there;
-- retire services and profile links without removing runtime data; and
-- preserve retired runtime data because this release intentionally ships no
-  automated purge; any future purge requires a separately reviewed path-safe
-  tool and a verified off-host backup.
-
-The earlier procedure remains recoverable from repository history for incident
-forensics. Repository history is evidence, not an active operator interface.

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 the PM's **heartbeat** systemd-timer tick
-(`.scripts/heartbeat.sh`). Under the pure-local runtime contract this timer
-performs board reconciliation only. 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 Telegram and 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 provisioning is outward-facing. It can configure 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 profile gateway and board-reconciliation `heartbeat` timer. |
-| `install-local.sh` | One-command local install (no cloud, macOS + Linux). |
-| `template/.scripts/heartbeat.sh` | The heartbeat runner: sentinel full-pass dispatch with its own cooldown and lock. |
-| `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.