docs: add scoped registrar recovery guidance
This commit is contained in:
parent
456a80c2f6
commit
105a34784b
4 changed files with 38 additions and 7 deletions
|
|
@ -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(
|
||||||
|
|
|
||||||
|
|
@ -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).
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
|
|
|
||||||
20
AGENTS.md
20
AGENTS.md
|
|
@ -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.
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue