the-custodian/canon/architecture/adr-005-cross-repo-workplans-project-repos.md

---
id: ADR-005
type: architecture-decision-record
title: "Cross-Repo Workplans Live in Dedicated Project Repos"
status: accepted
decided_by: Bernd Worsch
date: "2026-06-22"
tags: ["architecture", "state-hub", "workplans", "cross-repo", "project-repo", "source-of-truth", "lifecycle"]
---

# ADR-005: Cross-Repo Workplans Live in Dedicated Project Repos

## Status

Accepted.

## Context

ADR-001 established that workplans and work items originate as files in the
repository that owns them, so the State Hub can rebuild its coordination state
from repo-owned files alone. The repo-classification redesign (`CUST-WP-0050`)
takes the next step: it makes the **repo the primary anchor** for a workplan
(`workstreams.repo_id` becomes required) and **derives** the market-domain from
the repo's `.repo-classification.yaml` rather than maintaining a separate
`topic`/`domain` spine. Repos are the most stable, git-managed entities in the
ecosystem; binding to them is the most durable anchor available.

This raises an unavoidable question: **what anchors a genuinely cross-repo
workplan?** Some efforts coordinate change across many repositories — ecosystem
migrations, the FOS hub bootstrap (`CUST-WP-0025`), or `CUST-WP-0050` itself,
which touches ~70 repos. If every workplan must bind to exactly one repo:

- binding it to one arbitrary product repo misrepresents the work and pollutes
  that repo's history with coordination it does not own;
- leaving it unbound reintroduces the hub-only orphan that ADR-001 forbids;
- modelling it as an array of `repo_id`s breaks the "one stable anchor, clear
  ownership, clean lifecycle" property and complicates the rebuild principle.

## Decision

**A complex cross-repo workplan gets its own dedicated *project repo*.**

- The project repo is a real, git-managed repository. It owns the coordination
  workplan, its tasks, its decisions, and any cross-cutting artefacts. It is the
  required `repo` anchor for that workplan, satisfying the repo-primary-anchor
  rule without distorting any single product repo.
- The project repo is classified under the Repo Classification Standard, normally
  `category: project`. Its `domain`/tags describe the effort, not any one product.
- **Implementation still happens in the product repos.** Changes land via
  per-repo workplans and PRs in the repos being modified. The project repo
  *coordinates and references* that work (via dependency edges / links); it does
  not own product code.
- **On completion, the project repo is retired to archive — not deleted.** Its
  durable results live on in the product repos it modified (the merged changes
  are the outcome). The archived project repo remains as an immutable provenance
  record of the coordination, consistent with the append-only-memory value.

The project repo's completion record MUST list the product repos it modified and
link to the merged PRs/commits, so the trail survives archival.

## Lifecycle

```
draft → active → completed → archived
```

- **active** — work in progress; workplan `status: active`; repo live in Gitea
  and registered in the Hub.
- **completed** — all tasks done; completion record written (modified repos +
  links).
- **archived** — repo archived in Gitea and `status: archived` in the Hub. The
  workplan moves to `workplans/archived/` per the workplan convention. Results
  persist in the product repos; the project repo is read-only history.

## Naming

Project repos SHOULD be identifiable as such (e.g. a `proj-<slug>` prefix or a
dedicated grouping). Exact convention is deferred to `CUST-WP-0050` rollout
(tracked as an open question there), but the lifecycle and ownership rules above
are fixed by this ADR.

## Consequences

- **Pro:** every workplan — including cross-repo ones — has a stable,
  git-managed anchor; no hub-only orphans; the rebuild principle (ADR-001) holds.
- **Pro:** the classification standard applies uniformly; project repos are just
  repos with `category: project`.
- **Pro:** clean, explicit lifecycle; results are never lost on retirement
  because they live in the modified product repos.
- **Con:** proliferation of short-lived repos; requires discipline around the
  naming and archival convention.
- **Con:** cross-references between the project repo and the product repos it
  modified must be recorded deliberately, or the provenance trail degrades after
  archival.
- **Con:** judgement is required on *when* an effort is "complex enough" to merit
  a project repo versus a single-repo workplan; small cross-cutting changes
  should not spawn a repo.

## Alternatives Considered

- **Bind to a "lead" product repo.** Rejected: distorts that repo's history and
  creates ambiguous ownership.
- **Keep an optional hub-only topic for cross-repo coordination.** Rejected:
  reintroduces the soft, non-git-managed spine that `CUST-WP-0050` removes and
  ADR-001 discourages.
- **Multi-anchor workplan (array of repo_ids, no primary).** Rejected: breaks
  single-anchor simplicity, ownership clarity, and lifecycle modelling.

## Related

- ADR-001 — Workplans and Work Items Are Repository Artefacts
- `CUST-WP-0050` — Repo Classification & State Hub Registration Redesign (D1)
- `canon/standards/repo-classification-standard_v1.0.md`