From ec1808f9708123f0ecb7f7d19f8f1d20c4140620 Mon Sep 17 00:00:00 2001 From: Guillermo Montero Date: Thu, 17 Sep 2026 14:58:20 +0200 Subject: [PATCH] docs(setup): document the existing validate+init stale-relay resync path --- AGENTS.md | 1 + CHANGELOG.md | 3 +++ docs/setup-guide.md | 7 +++++++ 3 files changed, 11 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 89e4e97f8..4d96440a0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,6 +24,7 @@ Things that break silently. Never violate; when in doubt, read the named module' - No LLM calls in the orchestrator control loop. - Sessions complete only on hook Stop events or window death — never on LLM prose. Never add another completion path. Post-session state is re-verified deterministically (`verify.py`). +- The installed hook relay (`.bmad-loop/bmad_loop_hook.py`) is a copy laid down by `init`, so it goes stale when the orchestrator upgrades; `bmad-loop validate` flags that via the `hooks.relay-stale` warning, and `bmad-loop init` is the existing resync — re-run it to refresh the copy. That resync is reliable only when the relay was never installed before; if a stale marker already exists, re-running `init` after an upgrade that changes the registered command's shape can report "hooks already registered" without updating it (see [#563](https://github.com/bmad-code-org/bmad-loop/issues/563)). - `sprintstatus.advance()` is the orchestrator's sole write path to sprint-status.yaml (internally serialized cross-process since #469; the dev skill flips only spec frontmatter; the engine mirrors it onto the board pre-verify). Legal phase transitions live only in `statemachine.py`. - All git subprocess calls in `src/bmad_loop` go through the `_run_git` chokepoint in `verify.py` (timeouts, `LC_ALL=C`) — no bare subprocess git; `tests/test_portability_guard.py` enforces it. Tests, `scripts/`, and CI workflows deliberately spawn their own git: a harness must not depend on the artifact it validates. - Every new policy field needs an entry in `src/bmad_loop/data/settings/core.toml` (a sync test enforces defaults/options match `policy.py`). New core env vars register in `envvars.py`; plugin-owned env-var families stay with their plugin. diff --git a/CHANGELOG.md b/CHANGELOG.md index 5259aee07..658ab1515 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -167,6 +167,9 @@ breaking changes may land in a minor release. ### Changed +- **Docs: documented that bmad-loop validate detects a stale hook relay and bmad-loop init + resyncs it.** + - **`bmad-loop diagnose --json` reports `schema_version: 4`.** Journal `path` values become `path_present`; stale-restore and merge filename lists become counts. diff --git a/docs/setup-guide.md b/docs/setup-guide.md index f30138f1f..0b6ef9f54 100644 --- a/docs/setup-guide.md +++ b/docs/setup-guide.md @@ -325,6 +325,13 @@ bmad-loop validate --project yet, or `bmad-sprint-planning` hasn't run). On a fresh project that is **expected** — read its output as a readiness checklist, not an install failure. +`validate` also detects a stale copy of the installed hook relay +(`.bmad-loop/bmad_loop_hook.py`) with the `hooks.relay-stale` warning, and `bmad-loop init` is +the existing resync for it — re-run `init` to refresh the copy. That resync is reliable when +the relay was never installed before, but re-running `init` after an upgrade that changes the +registered command's shape can report "hooks already registered" without actually updating an +already-stale entry; see [#563](https://github.com/bmad-code-org/bmad-loop/issues/563). + For the dashboard itself, see [docs/tui-guide.md](tui-guide.md). For the full policy reference, see the [Policy section](../README.md#policy-bmad-looppolicytoml) of the README.