CUST-ADR-005 accepted · accepted-1 the-custodian reviewed 2026-06-22generated from canonical source — do not edit

Cross-Repo Workplans Live in Dedicated Project Repos

Source: the-custodian · canon/architecture/adr-005-cross-repo-workplans-project-repos.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb

Review due: 2026-12-22

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_ids 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 MUST use the prj-<kebab-slug> prefix.

Exact naming, required files (GOAL.md instead of durable-product INTENT.md), authority boundary, residual handoff, and archive procedure are defined in:

canon/standards/project-repository-flavor_v0.1.md

That standard closes the naming open question previously deferred to CUST-WP-0050 (D1a). The illustrative proj- form mentioned in earlier drafts is not used for new repositories.

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.