@delorenj/pjangler 1.1.5 → 1.2.2

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

@@ -0,0 +1,141 @@
+---
+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, gateway operation,
+consumer operation, 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

@@ -26,12 +26,12 @@ invocations).
 | 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> --inherit-config --no-alias` + mirror local 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` | 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 | `SKIP_RUNTIME_REPO=1` |
-| 30 telegram | Capture BotFather token, write to profile-local `.env`, enable hermes-telegram toolset | `SKIP_TELEGRAM=1` |
+| 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, hourly checkpoint timer | `SKIP_SYSTEMD=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 |
 
@@ -57,6 +57,8 @@ 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"
@@ -103,7 +105,7 @@ cd /home/delorenj/code/hermes-agent-template
 ```bash
 AGENT=bloodbank-pm
 systemctl --user start hermes-${AGENT}-consumer.service
-systemctl --user start hermes-${AGENT}-checkpoint.timer
+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:
@@ -165,17 +167,12 @@ op read 'op://DeLoSecrets/agent-hm-<repo>-<role>/.env' > agents/hermes/<role>/ru
 
 # Symlink the profile dir
 ln -sfn $PWD/agents/hermes/<role>/runtime ~/.hermes/profiles/<repo>-<role>
-cat > agents/hermes/<role>/runtime/profile.yaml <<'YAML'
-config:
-  inherit_from: default
-  save_mode: delta
-YAML
 
 # Re-enable systemd units
 systemctl --user enable hermes-<repo>-<role>-{gateway,consumer}.service
-systemctl --user enable hermes-<repo>-<role>-checkpoint.timer
+systemctl --user enable hermes-<repo>-<role>-heartbeat.timer
 systemctl --user start  hermes-<repo>-<role>-{consumer}.service
-systemctl --user start  hermes-<repo>-<role>-checkpoint.timer
+systemctl --user start  hermes-<repo>-<role>-heartbeat.timer
 ```
 
 ## Retire an agent (manual, until v1.1 ships retire.sh)
@@ -184,7 +181,7 @@ systemctl --user start  hermes-<repo>-<role>-checkpoint.timer
 AGENT=bloodbank-dev
 # 1. Stop daemons
 systemctl --user disable --now hermes-${AGENT}-{gateway,consumer}.service
-systemctl --user disable --now hermes-${AGENT}-checkpoint.timer
+systemctl --user disable --now hermes-${AGENT}-heartbeat.timer
 
 # 2. Delete hermes profile (cascades to symlinked runtime — make sure
 #    that's what you want!)
@@ -224,15 +221,16 @@ rm -rf agents/hermes/<role>
 - Tail consumer: `journalctl --user -fu hermes-<agent>-consumer.service`
 - Make sure something is actually publishing to `bloodbank.evt.v1.repo.<repo>.*`
 
-### Checkpoint timer not pushing
-- Look at the most recent checkpoint log: `tail ~/.hermes/profiles/<agent>/logs/checkpoint.log`
+### 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 legacy clone-based profile bug. New profiles use
-  `--inherit-config`; if you see nested profile dirs, remove the nested tree and
-  confirm `runtime/profile.yaml` contains `config.inherit_from: default`.
+- 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` references `/home/delorenj/code/hermes-agent/.venv/bin/hermes`. Override with `HERMES_BIN=/path/to/hermes ./agents/hermes/pm/hermes status`.
+- 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

@@ -2,20 +2,24 @@
 
 Status: Active operations runbook
 Applies to: every Hermes agent whose `runtime/` is a git submodule checkpointed
-by a `hermes-<agent>-<role>-checkpoint.service` systemd unit.
-
-This runbook fixes the failure where the hourly checkpoint service dies with
-**exit 128** and the agent's runtime "brain" stops being backed up. 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.
+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>-<role>-checkpoint.service
+systemctl --user status hermes-<agent>-heartbeat.service
 #   Active: failed (Result: exit-code) ... status=128/n/a
-#   ExecStart=.../agents/hermes/<role>/.scripts/checkpoint.sh
+#   the heartbeat invokes .../agents/hermes/<role>/.scripts/checkpoint.sh
 ```
 
 `checkpoint.sh` is just `cd runtime && git add -A && commit && push`. Run it by
@@ -123,9 +127,9 @@ git add -A --dry-run | awk '{print $2}' | while read -r f; do
 
 ```bash
 bash agents/hermes/<role>/.scripts/checkpoint.sh        # exits 0, pushes brain
-systemctl --user reset-failed hermes-<agent>-<role>-checkpoint.service
-systemctl --user start       hermes-<agent>-<role>-checkpoint.service
-systemctl --user show hermes-<agent>-<role>-checkpoint.service -p Result -p ExecMainStatus
+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
 ```
 
@@ -147,7 +151,7 @@ systemctl --user reset-failed <svc> && systemctl --user start <svc>
 ## Fleet sweep — this is rarely just one repo
 
 ```bash
-systemctl --user list-units --all '*-checkpoint.service' | grep -i failed
+systemctl --user list-units --all '*-heartbeat.service' | grep -i failed
 # for each failing agent, locate its runtime and run the repair script.
 ```
 

package/templates/hermes-agent/docs/{scrum-master → sentinel}/README.md

@@ -1,21 +1,29 @@
-# Scrum Master sentinel — developer handoff
-
-This guide is the entry point for continuing development of the **Scrum Master**
-role: a provider-agnostic, always-on ticket sentinel with an autonomous
-adversarial review (act, do not wait). 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 Scrum Master is
-
-The Scrum Master is a Hermes agent role whose core loop keeps 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.
+# 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
@@ -29,18 +37,16 @@ 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 (Drumjangler's
+- 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 engine runs on **Linux** (`systemd`) and **macOS** (`launchd`). The runner
-  uses `flock` on Linux and an atomic `mkdir` lock on macOS.
-- **Drumjangler** has been cut over to this engine (provider `linear`). Its
-  bespoke sentinel is retired. See
-  [Development guide: the Drumjangler cutover](development.md#the-drumjangler-cutover).
+- 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
 
@@ -53,10 +59,9 @@ curl -fsSL https://raw.githubusercontent.com/delorenj/hermes-agent-template/main
 ```
 
 It installs `hermes` and `copier` if missing, writes a host-correct local
-config, provisions the PM and Scrum Master roles, binds the Scrum Master to an
-existing board, and installs the sentinel as a `launchd` agent (macOS) or
-`systemd` timer (Linux). See [Development guide: local
-install](development.md#local-install-one-command).
+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]
@@ -64,7 +69,7 @@ install](development.md#local-install-one-command).
 > 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-a-scrum-master-manual) for local or lean
+> provisioning](development.md#provisioning-the-pm-manual) for local or lean
 > installs.
 
 ## Where the pieces live
@@ -73,21 +78,20 @@ All paths are relative to the repository root.
 
 | Path | What it is |
 | --- | --- |
-| `copier.yml` | Questions (`role`, `ticket_provider`, `with_scrum_master`) and the `_tasks` provisioning chain. |
-| `template/role.yaml.jinja` | The rendered role manifest, including the `ticket_provider` binding and `scrum_master` knobs. |
+| `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/75-scrum-master.sh` | Provisioning step that installs the sentinel scheduler (`systemd` timer on Linux, `launchd` agent on macOS). |
-| `template/.scripts/90-chain-scrum-master.sh` | Chains a Scrum Master provision when a PM opts in. |
+| `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/scrum-master/continuous-ticket-sentinel.sh` | The runner (heartbeat plus full-pass dispatch). |
-| `template/.scripts/scrum-master/continuous-ticket-sentinel.prompt.md.jinja` | The prompt the runner feeds to Hermes for a full pass. |
-| `template/.scripts/scrum-master/bin/` | Enforcement tools: `issue-autonomous-review.sh`, `issue-close-gate.sh`, `emit-event.py`. |
-| `template/.scripts/scrum-master/docs/` | Runtime protocol docs shipped to each deployment. |
+| `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/scrum-master/` directory you're reading now holds the **developer**
-docs for this template. The `template/.scripts/scrum-master/docs/` directory
+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.
 
@@ -98,8 +102,8 @@ the agent to read at run time. Keep the two in sync when behavior changes.
 - [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; the Drumjangler cutover record;
-  known gotchas; and the open roadmap.
+  workflow; provisioning and its `SKIP_*` flags; known gotchas; and the open
+  roadmap.
 
 ## Next steps for the incoming agent
 
@@ -111,8 +115,5 @@ The highest-value open work, in order:
 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. Give the Drumjangler Scrum Master its own runtime repo instead of the shared
-   symlink. See [Development guide: open
-   roadmap](development.md#open-roadmap).
-4. Confirm the first full Hermes pass after a live cutover reconciles the board
-   cleanly.
+3. Confirm the first full Hermes reconciliation pass on a freshly provisioned PM
+   reconciles the board cleanly.

package/templates/hermes-agent/docs/{scrum-master → sentinel}/architecture.md

@@ -1,36 +1,35 @@
-# Scrum Master architecture
+# Heartbeat sentinel architecture
 
-This guide explains how the Scrum Master engine works: the watch loop, the
-provider abstraction, the normalized state model, and the autonomous
+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.
 
-## The role
+## Who owns it
 
-The Scrum Master is a first-class Hermes role, a peer of the `pm` role. It's
-materialized into a project at `agents/hermes/scrum-master/` and carries its own
-`role.yaml`, runtime, prompt, enforcement tools, and a scheduler unit
-(`systemd` on Linux, `launchd` on macOS). The role id is `scrum-master`, and the
-display name is `<Repo> Scrum Master`.
+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 can provision it two ways:
+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).
 
-- **Standalone**, by running Copier with `--data role=scrum-master`.
-- **As a PM add-on**, by answering `yes` to the `with_scrum_master` question
-  during a `pm` provision. That chains a Scrum Master provision for the same
-  repo and provider through `90-chain-scrum-master.sh`.
-
-For the exact commands, see [Development guide:
-provisioning](development.md#provisioning-a-scrum-master-manual).
-
-## The watch loop
+## The heartbeat loop
 
 A scheduler (`systemd` timer on Linux, `launchd` agent on macOS) fires the
-runner, `template/.scripts/scrum-master/continuous-ticket-sentinel.sh`, about
-once a minute. The runner is a cheap heartbeat that decides whether a full,
-LLM-backed pass is worth running. This keeps cost low while staying responsive.
-
-The heartbeat reads the work-state file,
+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:
 
@@ -44,7 +43,7 @@ decisions:
 - `run:full`: none of the above hold, so the runner executes a full pass.
 
 A full pass runs `hermes chat` with the rendered prompt,
-`continuous-ticket-sentinel.prompt.md`. The prompt tells the agent to reconcile
+`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"
@@ -101,12 +100,12 @@ 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/scrum-master/docs/autonomous-delegated-review.md`. Here's the
+`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:
-`scrum_master.grace_hours` defaults to `0`, so the reviewer acts immediately. It
+`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
@@ -117,7 +116,7 @@ the project's horizon model, and the product north star.
 The reviewer then runs the decision gate:
 
 ```bash
-.scripts/scrum-master/bin/issue-autonomous-review.sh <ISSUE> <REPORT> --close
+.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
@@ -173,8 +172,8 @@ 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/scrum-master/bin/emit-event.py`, and the event types are
-documented in `template/.scripts/scrum-master/docs/bloodbank-events.md`. Events
+`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.
 
@@ -182,18 +181,20 @@ local spool that doesn't require NATS, so the loop stays reliable offline.
 
 A full pass moves through these components in order:
 
-1. The scheduler (`systemd` timer or `launchd` agent) triggers the runner.
-2. The runner's heartbeat decides `run:full` and calls `hermes chat` with the
-   prompt.
+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 `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 heartbeat.
+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