Archived

This repository has been archived on 2026-07-08. You can view files and clone it. You cannot open issues or pull requests or push a commit.

Files

tegwick 50f4564561 Resolve CUST-WP-0050 D1: repo-anchored model + ADR-005

Adopt the repo as the primary workplan anchor: repo_id becomes required,
market-domain is derived from each repo's classification, and the
domain/topic spine is demoted/retired (RepoGoal becomes the goal primitive).
Add task T10 for the re-anchor plus the workstream -> workplan rename across
schema/API/MCP.

Add ADR-005 (Cross-Repo Workplans Live in Dedicated Project Repos): complex
cross-repo efforts get their own project repo (category: project) as the
anchor, retired to archive on completion with results living on in the
modified product repos. Rewrite D1 as resolved and add D1a for the
project-repo naming/archival convention.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-22 01:36:31 +02:00

5.1 KiB

Raw Blame History

id, type, title, status, decided_by, date, tags

type

title

status

decided_by

date

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

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

5.1 KiB Raw Blame History