# 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`.