citation-evidence/docs/decisions/ADR-0002-monorepo-vs-polyrepo.md

# ADR-0002 — Monorepo vs polyrepo for the six subsystems

- Status: accepted
- Date: 2026-05-24
- Decided: 2026-06-22
- Workplan: CENG-WP-0002-T01

## Context

The umbrella-first MVP lives entirely in `citation-evidence/` under
`src/{anchor,source,binder,work,app}/` with shared types and engine services
in the extracted `@citation-evidence/engine` package (`citation-engine` repo).

Each remaining folder is named after its eventual extracted package. At some
point — driven by an external consumer needing one subsystem, or by independent
release cadence — code will move out into its sister repo.

We need a written answer to: when that moment comes, do we (a) keep one
repository with pnpm workspaces, (b) split into six independent repos with
published packages, or (c) something in between?

The decision affects: dependency management, release cadence, CI surface
area, contributor friction, and how `wiki/SharedContracts.md` is enforced
across the boundary.

## Options

- **A. Single repo, pnpm workspaces**
  - Pros: one CI, one version of every dep, atomic cross-package PRs, easy
    refactors. Shared contracts enforced by the type checker.
  - Cons: any consumer outside this repo needs a private registry or
    git-tag-based installs. Release cadence is shared.

- **B. Six independent repos, published packages**
  - Pros: clean external publish story, independent versioning. Forces the
    contract to be a real package boundary.
  - Cons: dependency upgrades require coordinated PR trains. Refactors that
    span subsystems become multi-repo dances. Hard to keep
    `SharedContracts.md` in sync across repos.

- **C. Hybrid — monorepo with publishable workspaces**
  - Pros: best of both: one repo for dev, but `pnpm publish` from any
    workspace package. Tools: changesets / nx / turbo.
  - Cons: more tooling to learn; per-workspace `package.json` cuts to
    maintain.

## Decision

**B — six independent repos with published packages**, using **`link:` sibling
dependencies during local development** until a registry is configured.

Rationale:

1. The ecosystem is already organized as six sister repos plus the umbrella;
   independent repos match the documented architecture.
2. `citation-engine` extraction (`CENG-WP-0001`) and umbrella wireup
   (`CE-WP-0009`) prove the `link:../citation-engine` dev workflow.
3. Publishing can be deferred — no registry is configured yet — without
   blocking extraction of the remaining subsystems.
4. Option C adds tooling overhead before any external consumer exists.

## Consequences

- **Local dev:** sister repos sit as siblings under `~/` (or equivalent).
  Consumers declare `"@citation-evidence/engine": "link:../citation-engine"`.
- **Publishing:** when a registry is chosen, bump `@citation-evidence/engine`
  semver and replace `link:` with the registry version in consumer repos.
- **Contracts:** `citation-evidence/wiki/SharedContracts.md` stays authoritative;
  `citation-engine/wiki/SharedContracts.md` is a conformance copy (see
  `citation-engine/wiki/README.md`).
- **Versioning:** engine package semver tracks API/contract changes; umbrella
  and sister repos pin or range-pin on publish.
- **CI:** each repo runs its own test/lint pipeline; cross-repo integration
  tests remain in `citation-evidence` until subsystems extract fully.