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.