76 lines
2.6 KiB
Markdown
76 lines
2.6 KiB
Markdown
|
# Workplan structure and registration
|
||
|
|
|
||
|
|
**Read this before adding or editing workplans in this repository.**
|
||
|
|
|
||
|
|
Workplans here do not currently register with the State Hub. This note records
|
||
|
|
why, and what has to change. Nothing has been rewritten — the files are left as
|
||
|
|
they are so the cleanup can happen when this repository is next picked up.
|
||
|
|
|
||
|
|
## What the hub expects
|
||
|
|
|
||
|
|
A workplan is a Markdown file in `workplans/` whose frontmatter declares:
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
---
|
||
|
|
id: PREFIX-WP-NNNN # canonical record id; one prefix per repository
|
||
|
|
type: workplan # REQUIRED — this is what identifies the file
|
||
|
|
title: "..."
|
||
|
|
domain: <sector domain> # see the Repo Classification Standard
|
||
|
|
repo: <repo slug>
|
||
|
|
status: proposed | ready | active | blocked | backlog | finished | archived
|
||
|
|
owner: <who>
|
||
|
|
created: "YYYY-MM-DD"
|
||
|
|
updated: "YYYY-MM-DD"
|
||
|
|
---
|
||
|
|
```
|
||
|
|
|
||
|
|
Tasks are fenced blocks inside the file:
|
||
|
|
|
||
|
|
````markdown
|
||
|
|
```task
|
||
|
|
id: PREFIX-WP-NNNN-T01
|
||
|
|
status: wait | todo | progress | done | cancel
|
||
|
|
priority: high | medium | low
|
||
|
|
```
|
||
|
|
````
|
||
|
|
|
||
|
|
Note the two vocabularies differ. `done` and `todo` are **task** statuses.
|
||
|
|
A workplan is `finished`, never `done`.
|
||
|
|
|
||
|
|
## Why these files are invisible today
|
||
|
|
|
||
|
|
The scanner selects files by `type: workplan`. Anything else in frontmatter —
|
||
|
|
`kind:`, or no type at all — is skipped silently, so the file is not merely
|
||
|
|
unregistered but unseen: it does not appear as a gap, an error, or a warning.
|
||
|
|
|
||
|
|
Where a workplan also carries a status outside the list above, that status
|
||
|
|
cannot be projected even once the file is found.
|
||
|
|
|
||
|
|
## How registration works
|
||
|
|
|
||
|
|
Files originate the work; the hub holds a projection of them (`ADR-001`,
|
||
|
|
`ADR-012`). Never create records in the hub by hand — write the file, commit,
|
||
|
|
and let the registrar derive the record:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
uv run --project ~/repo-manager rmgr registrar-reconcile \
|
||
|
|
--path . --confirm-primary --push
|
||
|
|
```
|
||
|
|
|
||
|
|
The registrar requires a clean worktree, and it will refuse a workplan whose
|
||
|
|
backing file is not committed and pushed — a hub record whose source is only
|
||
|
|
local cannot be re-derived by anyone else.
|
||
|
|
|
||
|
|
## When cleaning this repository up
|
||
|
|
|
||
|
|
1. Decide whether each file is genuinely a workplan. Some may be design notes or
|
||
|
|
product documents that simply live in `workplans/`; those belong elsewhere,
|
||
|
|
or should keep a non-workplan type deliberately.
|
||
|
|
2. For real workplans: set `type: workplan`, map statuses to the workplan
|
||
|
|
vocabulary, add the missing fields.
|
||
|
|
3. Commit, push, then run the registrar above.
|
||
|
|
|
||
|
|
References: `the-custodian/.claude/rules/workplan-convention.md`,
|
||
|
|
`canon/architecture/adr-001-workplans-as-repo-artefacts.md`,
|
||
|
|
`canon/architecture/adr-012-projection-source-and-preliminary-overlay.md`.
|