ci / check (push) Failing after 3s

Details

docs(workplans): note how workplans must be structured to register

These workplans do not reach the State Hub. The scanner selects files by
'type: workplan', so files declaring something else are skipped silently —
not flagged as a gap, an error, or a warning, simply unseen.

Records what the hub expects and how registration works, so the cleanup can
be done deliberately when this repository is next picked up. No workplan file
has been rewritten.

Refs CUST-WP-0068-T04

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 2583210@bnt-lap001
Assistant-Session: f2bff2d5-e9b2-4338-92ca-10282a927006

2026-08-25 22:22:51 +02:00

2.6 KiB

Raw Permalink Blame History

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:

---
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:

```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:

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

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.
For real workplans: set type: workplan, map statuses to the workplan vocabulary, add the missing fields.
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.

2.6 KiB Raw Permalink Blame History