docs(canon): add ADR-001 — workplans are repository artefacts
State-hub is a read/cache layer. Workplans and work items must originate as Markdown files in their native repository so the hub can rebuild its full representation from registered repos alone (the rebuild principle). Establishes: - canon/architecture/ directory for ADRs - Workplan file convention (frontmatter schema, task embedding) - Rebuild sequence (migrate → seed-domains → sync-workplans) - Marks DB-first v0.3/v0.5 records as legacy pending sync tooling Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
183
canon/architecture/adr-001-workplans-as-repo-artefacts.md
Normal file
183
canon/architecture/adr-001-workplans-as-repo-artefacts.md
Normal file
@@ -0,0 +1,183 @@
|
||||
---
|
||||
id: ADR-001
|
||||
type: architecture-decision-record
|
||||
title: "Workplans and Work Items Are Repository Artefacts"
|
||||
status: accepted
|
||||
decided_by: Bernd Worsch
|
||||
date: "2026-02-28"
|
||||
tags: ["architecture", "state-hub", "workplans", "source-of-truth", "rebuild-principle"]
|
||||
---
|
||||
|
||||
# ADR-001: Workplans and Work Items Are Repository Artefacts
|
||||
|
||||
## Status
|
||||
|
||||
Accepted.
|
||||
|
||||
## Context
|
||||
|
||||
During early State Hub development (v0.1–v0.4), workstreams and tasks were
|
||||
created directly in the PostgreSQL database via MCP bootstrap tools
|
||||
(`create_workstream`, `create_task`). This made the database the **origin** of
|
||||
work items — not a cache or index. The pattern was convenient for rapid
|
||||
bootstrapping but is architecturally wrong for a system built on the values of
|
||||
auditability, reversibility, and local-first sovereignty.
|
||||
|
||||
The trigger for formalising this decision was the creation of the v0.5
|
||||
workplan ("Dynamic Domains & Multi-Repo") directly in the state-hub database
|
||||
without a corresponding file artefact in any repository.
|
||||
|
||||
## Decision
|
||||
|
||||
**Workplans and work items MUST originate as Markdown files in the repository
|
||||
that owns them.** The Custodian State Hub indexes and caches those artefacts
|
||||
but is never their origin.
|
||||
|
||||
Formally: the state-hub must (theoretically, given sufficient compute and
|
||||
time) be able to **rebuild its full representation** of repositories, their
|
||||
workplans, tasks, decisions, and dependencies by reading only the files in the
|
||||
registered repositories. No information that matters for coordination should
|
||||
exist solely in the database.
|
||||
|
||||
### Corollaries
|
||||
|
||||
1. **Repository is authoritative.** A workplan file is the canonical record.
|
||||
The state-hub database row is a materialized cache of that file.
|
||||
|
||||
2. **Database is disposable.** Dropping and re-creating the database from
|
||||
registered repository files must produce an equivalent state. The database
|
||||
is an operational convenience, not a primary store.
|
||||
|
||||
3. **MCP bootstrap tools become index/sync tools.** `create_workstream` and
|
||||
`create_task` are acceptable as convenience wrappers only if they write the
|
||||
file first and then register the row. Using them to write DB-only records
|
||||
violates this ADR.
|
||||
|
||||
4. **The rebuild principle implies a sync mechanism.** There must be a defined
|
||||
path (`make sync-workplans` or equivalent) by which the state-hub reads
|
||||
workplan files from registered repositories and upserts its database state.
|
||||
|
||||
## Workplan File Convention
|
||||
|
||||
Each workplan lives in a `workplans/` directory in the repository that owns
|
||||
the work. The owning repository is identified by domain.
|
||||
|
||||
### Location
|
||||
|
||||
```
|
||||
<repo-root>/workplans/<id>-<slug>.md
|
||||
```
|
||||
|
||||
Examples:
|
||||
- `the-custodian/workplans/CUST-WP-0005-dynamic-domains.md`
|
||||
- `railiance/workplans/RAIL-WP-0001-three-phoenix.md`
|
||||
|
||||
### Frontmatter Schema
|
||||
|
||||
```yaml
|
||||
---
|
||||
id: CUST-WP-0005 # human-readable workplan ID, unique per repo
|
||||
type: workplan
|
||||
title: "State Hub v0.5 — Dynamic Domains & Multi-Repo"
|
||||
domain: custodian # must match a registered domain slug
|
||||
status: active # active | completed | archived
|
||||
owner: custodian
|
||||
topic_slug: custodian # maps to a state-hub Topic slug
|
||||
created: "2026-02-28"
|
||||
updated: "2026-02-28"
|
||||
---
|
||||
```
|
||||
|
||||
### Task Items
|
||||
|
||||
Tasks are embedded in the workplan file as headed sections. Each task
|
||||
section carries its own YAML block:
|
||||
|
||||
```markdown
|
||||
## P1.1 — Create `domains` table + Alembic migration
|
||||
|
||||
```task
|
||||
id: CUST-WP-0005-T001
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
Task description prose here.
|
||||
```
|
||||
|
||||
The state-hub parses these embedded task blocks during ingestion and upserts
|
||||
rows in the `tasks` table. The `id` field is the stable external key; the
|
||||
state-hub UUID is internal and opaque.
|
||||
|
||||
### Decision Items
|
||||
|
||||
Decisions are separate files or embedded sections following the same pattern,
|
||||
using `type: decision` in frontmatter.
|
||||
|
||||
## Rebuild Principle
|
||||
|
||||
The rebuild sequence for a clean state-hub:
|
||||
|
||||
1. `make migrate` — create schema
|
||||
2. `make seed-domains` — insert domain rows (domains.yaml in canon/)
|
||||
3. For each registered repository: `make sync-workplans REPO=<slug>` — parse
|
||||
workplan files and upsert workstreams, tasks, decisions
|
||||
4. `make sync-progress` — replay progress events from episodic memory logs
|
||||
|
||||
After step 4 the database must be functionally equivalent to the live state.
|
||||
|
||||
## Consequences
|
||||
|
||||
### Immediate
|
||||
|
||||
- The v0.5 and v0.3 workplans created DB-first in this session are **legacy
|
||||
records** that violate this ADR. Remediation: write the corresponding
|
||||
workplan files, then mark the DB rows as `source: db-legacy` until a sync
|
||||
mechanism can reconcile them.
|
||||
|
||||
- The state-hub CLAUDE.md design-boundary note must be updated: the MCP
|
||||
bootstrap tools are permitted only as write-through tools (file + DB), never
|
||||
as DB-only tools.
|
||||
|
||||
### Medium Term
|
||||
|
||||
- A `make sync-workplans` command must be implemented as part of the
|
||||
managed-repos / contribution-tracking infrastructure (see v0.3 workplan).
|
||||
|
||||
- The `managed_repos` table is the prerequisite: the state-hub must know which
|
||||
repositories to scan.
|
||||
|
||||
- Workplan file format must be versioned and parsed by a dedicated loader
|
||||
(`state-hub/scripts/sync_workplans.py`).
|
||||
|
||||
### Long Term
|
||||
|
||||
- When the state-hub grows to cover multiple users or teams, this principle
|
||||
ensures that no coordination state can be lost by a database failure.
|
||||
Every repository is its own resilient shard of the coordination graph.
|
||||
|
||||
- This is the foundation for the "transgenerational" property: workplans in
|
||||
git survive database migrations, cloud provider changes, and system
|
||||
rebuilds.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
**Database-first with export:** Create in DB, export to files on demand.
|
||||
Rejected: export is easily skipped and files become secondary/stale.
|
||||
|
||||
**Files-only, no database:** Parse files on every query.
|
||||
Rejected: impractical at scale; the database is a necessary cache for
|
||||
cross-repo aggregation and real-time dashboard queries.
|
||||
|
||||
**Hybrid with explicit sync flag:** Mark some records as "db-authoritative"
|
||||
and others as "file-authoritative."
|
||||
Rejected: introduces ambiguity about which records matter; violates the
|
||||
"single source of truth" principle.
|
||||
|
||||
## Related
|
||||
|
||||
- Custodian Constitution v0.1 §2 (Powers) — canon changes require review gate
|
||||
- ADR-000 (forthcoming) — overall Custodian architecture principles
|
||||
- State Hub v0.3 workplan — `sync_workplans.py` is a Phase 4 deliverable
|
||||
- `canon/values/foundational_values_v0.1.md` — Local-first, Auditability,
|
||||
Reversibility
|
||||
Reference in New Issue
Block a user