A sidecar daemon for the Hermes Kanban workflow that keeps a board un-stuck on its own: when a task hits one of the corner cases this controller has catalogued, the matching watchdog resolves it — or pings you — without anyone rediscovering the problem by hand. The problems stay fixed, and the board's history explains every action taken.
Two halves run side by side:
- Everyday watchdogs. A daemon plus cron-driven watchdogs watch Kanban execution and act on catalogued corner cases: reviewer defect blocks automatically get a deduplicated fix card; when that fix is verified merged into the canonical branch, the blocked review completes and its gated children are promoted; the highest-priority card waiting on your input is unblocked as soon as the board allows; a task created blocked gets its missing block event written before the dispatcher can silently promote it; a review child stranded by a parent that already carries completion evidence is archived — with evidence, fail-closed. Alongside these, watchdogs ping you when a task waits on input, a dispatcher death leaves a silent block, a done card is missing its review pair, or decisions stall. Git admission for protected refs ships as the Outcome Guard: operator-registered contracts plus a Git hook that denies unprotected canonical-ref updates.
- Daily reflection. Once a day (you choose when), the controller deterministically collects metrics on the previous day's executions and makes a single LLM call proposing improvements to the orchestration layer — not to fix tasks, but to grow the catalogue so what went wrong doesn't repeat.
One diagram covers both: the everyday watcher tick (observe → decide → act) and the nightly loop that produces the daily reflection report.
Configuration is two lines: the model for the LLM reflection, and the time of day it runs.
- A review blocked on a code defect gets a fix card on its own. When that fix merges, the review completes and every card gated behind it resumes — no one re-reads the board to notice.
- The one card that needs you is pinged to you as soon as the board allows it, instead of sitting in a list you have to sweep.
- A task that would have been promoted by the dispatcher before its gate was recorded gets that gate written first, so "ready" still means ready.
- A review stranded behind a parent that already carries the evidence is retired with that evidence attached, instead of blocking its lane forever.
- You run Hermes with a Kanban board and stuck tasks accumulate faster than you can unblock them by hand.
- You want observed orchestration failures catalogued and prevented, not rediscovered.
- You want a daily self-review loop that audits the orchestration layer and routes accepted findings onto the board.
- You want Git admission enforcement for protected refs.
Do not reach for it to open or edit native Hermes source, config, or task databases — that safety boundary is absolute. The long-game intent is for fixes to land in Hermes itself so the sidecar retires; docs/upstream-mapping.md tracks which catalogued case maps to which upstream fix and what must be true before each watchdog retires.
Requires Python 3.11+, uv for the dev/test environment, and a running Hermes instance with Kanban boards. Zero runtime third-party dependencies. Cron drives the watchdog cadence; systemd is optional and always opt-in.
git clone https://github.com/andrepontesmelo/hkrc
cd hkrc
uv sync --dev
uv run pytest # full suite green before you rely on the checkout
python3 scripts/hkrc_release.py install --instance-root <instance-root>
<instance-root>/bin/hkrc init # writes controller config + state DBThe release never installs, enables, or starts a service — that stays an operator action. The full fresh-machine walkthrough (executable path, systemd opt-in, cron reconciliation, upgrade/rollback) is docs/outcome-guard.md § Install on a fresh machine.
Audit the controller config before deploying one you did not write: the config surface is the model for the daily LLM reflection plus the daily-reflection time — scope exactly that, and start every watchdog with --dry-run.
uv run pytest is green. The suite includes the tests for every watchdog above — the same catalogue the daemon acts on.
- The daemon takes automated recovery actions on catalogued corner cases (fix-card creation, review completion on verified merge, pick-gate advance, missing-event guard, deadlock archive). Anything outside the catalogue is left untouched, and every action is logged with its evidence.
- The agent friction-flag path has no detection mechanism: agents append flags themselves; nothing scans sessions or raises findings. The daily loop revisits flags as report lines and stats only.
- The harness loop's shipped-fix retro is report-only: it never creates a kanban card, and any failure degrades to a labelled line without touching the run or a deploy.
- A
github:install resolves the default branch at install time — pin a tag for reproducibility.
- Docs index — architecture, development, outcome guard, persona-matrix runbook
- Decision-latency watcher — why stalled decisions escalate, how the watchdog cadence is computed
- Harness learning loop prompt — the nightly self-review loop and escalation rule
- Persona matrix + runbook — role/persona drift detection
- CONTRIBUTING.md · SECURITY.md · LICENSE
