CUST-ADR-001 accepted · accepted-1 the-custodian reviewed 2026-02-28generated from canonical source — do not edit

Workplans and Work Items Are Repository Artefacts

Source: the-custodian · canon/architecture/adr-001-workplans-as-repo-artefacts.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb

Review due: 2026-08-28

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.
  1. 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.
  1. 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.
  1. 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

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

## P1.1 — Create `domains` table + Alembic migration

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.

Workplan Closure Protocol

When a workplan is about to be marked finished, the responsible agent MUST perform a closure review before writing the status change. This prevents the stale-task accumulation that this ADR was designed to make detectable.

Steps

  1. Query all non-done tasks in the workplan via GET /tasks/?workplan_id=<uuid> (legacy alias: workstream_id; filter for todo, in_progress, blocked).
  1. Classify each task into one of three outcomes:
OutcomeAction
Done — work was completed, DB record just wasn't updatedPATCH /tasks/{id}/ {"status": "done"}
Cancelled — dropped, superseded, or out of scopePATCH /tasks/{id}/ {"status": "cancelled", "blocking_reason": "<why>"}
Carry-forward — genuinely unfinished, belongs in the next runLeave open; note in closure review; trigger new workplan
  1. Append a ## Closure Review section to the workplan file:
   ## Closure Review — YYYY-MM-DD

   **Outcome:** All tasks completed / N tasks carried forward / N tasks dropped.

   ### Completed (DB updated)
   - TASK-ID — title

   ### Cancelled (dropped)
   | Task | Reason |
   |------|--------|
   | TASK-ID — title | Superseded by X |

   ### Carried forward
   | Task | Target workplan |
   |------|----------------|
   | TASK-ID — title | CUST-WP-XXXX |
  1. If any tasks are carried forward: do not mark the workplan finished yet. Create the new workplan file (or amend an existing active one), then close the current workplan.
  1. Update the workplan frontmatter status: finished and updated: date.
  1. Mark the workplan finished in the state hub via MCP or API (update_workplan_status).

Daily Stale-Task Cleanup

As a safety net for cases where the closure review was skipped or incomplete, a cleanup script cancels any surviving open tasks in completed/archived workstreams:

cd ~/the-custodian/state-hub
make cleanup-stale            # run immediately
# or add to cron:
# 0 3 * * * cd ~/the-custodian/state-hub && make cleanup-stale

The script (scripts/cleanup_stale_tasks.py) emits a cleanup progress event recording which tasks were cancelled and in which workstreams. Tasks cancelled by the cleanup carry a blocking_reason noting they should be verified against the workplan file.

The closure review is the primary mechanism; the cleanup is the fallback. If the cleanup regularly cancels tasks, it signals that closure reviews are being skipped — that is the process failure to address, not just the stale tasks.