docs: add scoped registrar recovery guidance
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
CI Smoke / container-smoke (push) Successful in 1s

This commit is contained in:
codex 2026-08-21 21:38:35 +02:00
parent 456a80c2f6
commit 105a34784b
4 changed files with 38 additions and 7 deletions

View file

@ -17,7 +17,7 @@ roadmap phase. **Wait for approval before creating.**
**Step 4 — Write the workplan file; fix-consistency registers it (ADR-001)** **Step 4 — Write the workplan file; fix-consistency registers it (ADR-001)**
``` ```
workplans/RAILIANCE-WP-NNNN-<slug>.md ← write this, commit it workplans/RPF-WP-NNNN-<slug>.md ← write this, commit it
``` ```
Then register by running the consistency check — do **not** call Then register by running the consistency check — do **not** call
`create_workplan`/`create_task` yourself; manual registration duplicates what `create_workplan`/`create_task` yourself; manual registration duplicates what
@ -29,6 +29,11 @@ C-06 creates the hub workplan + tasks and writes `state_hub_workstream_id`
(legacy frontmatter name — holds the workplan UUID) and `state_hub_task_id` (legacy frontmatter name — holds the workplan UUID) and `state_hub_task_id`
back into the file. back into the file.
If C-06/C-11 is skipped on a non-registrar host, commit and push the workplan,
then run `uv run --project ~/repo-manager rmgr registrar-reconcile --path .
--confirm-primary --push` once. Never export registrar authority directly or
create hub rows by hand.
**Step 5 — Record the setup** **Step 5 — Record the setup**
``` ```
add_progress_event( add_progress_event(

View file

@ -61,6 +61,10 @@ If no workplans: follow First Session Protocol (`first-session.md`).
> and run `fix-consistency`; C-06 registers the workplan and tasks and writes > and run `fix-consistency`; C-06 registers the workplan and tasks and writes
> IDs back into the file. Manual registration creates duplicates when > IDs back into the file. Manual registration creates duplicates when
> fix-consistency runs. Work structure belongs in repo files (ADR-001). > fix-consistency runs. Work structure belongs in repo files (ADR-001).
> A non-registrar C-06/C-11 skip is handled once with
> `uv run --project ~/repo-manager rmgr registrar-reconcile --path .
> --confirm-primary --push` after committing and pushing file-backed work.
> Never set registrar authority directly or retry the same sync repeatedly.
> >
> Legacy: `create_workstream` and `/workstreams/` remain as metered aliases — > Legacy: `create_workstream` and `/workstreams/` remain as metered aliases —
> see `workplan-convention.md` (compatibility footnote). > see `workplan-convention.md` (compatibility footnote).

View file

@ -26,6 +26,18 @@ visible at session start. Pick one up by creating the workplan file, committing,
and running `statehub fix-consistency` — C-06 registers the workplan in the hub. and running `statehub fix-consistency` — C-06 registers the workplan in the hub.
Never register by hand with `create_workplan` (legacy MCP alias: `create_workstream`). Never register by hand with `create_workplan` (legacy MCP alias: `create_workstream`).
If C-06/C-11 is skipped because this host is not the identifier registrar,
further retries cannot help. Do not set `STATEHUB_REGISTRAR` or create hub rows
manually. Commit and push the file-backed work, then run once:
```bash
uv run --project ~/repo-manager rmgr registrar-reconcile \
--path . --confirm-primary --push
```
If unavailable, send one deduplicated request to `repo-manager` and continue
from the authoritative files.
Task blocks use this shape: Task blocks use this shape:
```task ```task
@ -46,7 +58,7 @@ fix-consistency. Do not edit or rename it.
**Workplan** is the fleet term — see **Workplan** is the fleet term — see
`the-custodian/canon/standards/workplan-terminology-fleet_v0.1.md`. `the-custodian/canon/standards/workplan-terminology-fleet_v0.1.md`.
**Workplan** is legacy only: some API routes (`/workstreams/`), params **Workstream** is legacy only: some API routes (`/workstreams/`), params
(`workstream_id`), MCP aliases (`create_workstream`), and the frontmatter field (`workstream_id`), MCP aliases (`create_workstream`), and the frontmatter field
above remain until `STATE-WP-0069` retires them via legacy-meter. Treat those above remain until `STATE-WP-0069` retires them via legacy-meter. Treat those
identifiers as workplan IDs. Prefer `GET /workplans/` and `workplan_id` in new identifiers as workplan IDs. Prefer `GET /workplans/` and `workplan_id` in new

View file

@ -104,6 +104,15 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
``` ```
Coding agents should run this directly; ask the operator only if the CLI or Coding agents should run this directly; ask the operator only if the CLI or
State Hub API is unavailable. This syncs task status from files into the hub DB. State Hub API is unavailable. This syncs task status from files into the hub DB.
If C-06/C-11 reports that this host is not the identifier registrar, do not
retry, set `STATEHUB_REGISTRAR`, or create hub rows manually. Commit and push
the file-backed work, then invoke repo-manager once:
```bash
uv run --project ~/repo-manager rmgr registrar-reconcile \
--path . --confirm-primary --push
```
If unavailable, send one deduplicated registrar request to `repo-manager`;
missing UUIDs do not block continued work from the repository files.
--- ---
@ -172,7 +181,7 @@ read/cache/index layer that rebuilds from files.
**File location:** `workplans/RPF-WP-NNNN-<slug>.md` **File location:** `workplans/RPF-WP-NNNN-<slug>.md`
**Archived location:** finished workplans may move to **Archived location:** finished workplans may move to
`workplans/archived/YYMMDD-RAILIANCE-WP-NNNN-<slug>.md`. The `YYMMDD` prefix is `workplans/archived/YYMMDD-RPF-WP-NNNN-<slug>.md`. The `YYMMDD` prefix is
the completion/archive date; the frontmatter `id` does not change. the completion/archive date; the frontmatter `id` does not change.
**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use **Ad Hoc Tasks:** small opportunistic fixes discovered during a session use
@ -184,7 +193,7 @@ anything needing analysis, design, approval, dependencies, or multiple phases.
```yaml ```yaml
--- ---
id: RAILIANCE-WP-NNNN id: RPF-WP-NNNN
type: workplan type: workplan
title: "..." title: "..."
domain: financials domain: financials
@ -208,7 +217,7 @@ derived health labels, not frontmatter statuses.
## Task Title ## Task Title
` ` `task ` ` `task
id: RAILIANCE-WP-NNNN-T01 id: RPF-WP-NNNN-T01
status: wait | todo | progress | done | cancel status: wait | todo | progress | done | cancel
priority: high | medium | low priority: high | medium | low
state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit
@ -221,5 +230,6 @@ Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blo
To create a new workplan: To create a new workplan:
1. Write the file following the format above 1. Write the file following the format above
2. Notify the custodian operator to run `make fix-consistency REPO=railiance-platform` 2. Run `statehub fix-consistency` locally.
(or send a message to the hub agent via `POST /messages/`) 3. On a non-registrar C-06/C-11 skip, use the scoped repo-manager command above
once. Never export registrar authority directly or send duplicate requests.