generated from coulomb/repo-seed
tegwick
697bc90780
Resolve ADR-0002 in umbrella, add install docs, contract sync runbook, publishing checklist, and package files whitelist.
154 lines
4.6 KiB
Markdown
154 lines
4.6 KiB
Markdown
---
|
|
id: CENG-WP-0002
|
|
type: workplan
|
|
title: "Package distribution — ADR-0002, publish readiness, contract sync"
|
|
domain: citation_evidence
|
|
repo: citation-engine
|
|
status: done
|
|
owner: codex
|
|
topic_slug: citation_evidence_mvp
|
|
created: "2026-06-22"
|
|
updated: "2026-06-22"
|
|
depends_on_workplan: CENG-WP-0001
|
|
state_hub_workstream_id: "ccd217a2-572d-435d-9a29-e0a55b6a4311"
|
|
spec_refs:
|
|
- ../citation-evidence/docs/decisions/ADR-0002-monorepo-vs-polyrepo.md
|
|
- ../citation-evidence/wiki/SharedContracts.md
|
|
- ../citation-evidence/wiki/DependencyMap.md
|
|
---
|
|
|
|
# CENG-WP-0002 — Package Distribution
|
|
|
|
Make `@citation-evidence/engine` consumable beyond a sibling `link:` checkout:
|
|
resolve the monorepo-vs-polyrepo decision, document the install story for sister
|
|
repos, and prepare optional registry publish.
|
|
|
|
Prerequisite: `CENG-WP-0001` complete. `CE-WP-0009` (umbrella wireup) can
|
|
proceed in parallel using `link:`; publish tasks here depend on T01.
|
|
|
|
## Dependency order
|
|
|
|
```
|
|
T01 (resolve ADR-0002)
|
|
└─ T02 (consumer install docs + export surface)
|
|
└─ T03 (SharedContracts sync runbook)
|
|
└─ T04 (publish readiness — optional until registry chosen)
|
|
```
|
|
|
|
---
|
|
|
|
## T01 — Resolve ADR-0002
|
|
|
|
```task
|
|
id: CENG-WP-0002-T01
|
|
status: done
|
|
priority: critical
|
|
depends_on: []
|
|
```
|
|
|
|
Fill in `citation-evidence/docs/decisions/ADR-0002-monorepo-vs-polyrepo.md`:
|
|
|
|
- **Decision** — pick A, B, or C for the citation-evidence ecosystem.
|
|
- **Recommended default** (if no strong preference): **B — six independent repos
|
|
with published packages**, using `link:../citation-engine` during local dev
|
|
until a registry is configured.
|
|
- **Consequences** — how sister repos install engine, how versions bump, how
|
|
`SharedContracts.md` stays authoritative.
|
|
|
|
Stop and ask the repo owner if the choice is genuinely ambiguous.
|
|
|
|
**Acceptance:** ADR status moves from `proposed` to `accepted`; decision and
|
|
consequences sections are filled.
|
|
|
|
---
|
|
|
|
## T02 — Consumer install docs and export surface
|
|
|
|
```task
|
|
id: CENG-WP-0002-T02
|
|
status: done
|
|
priority: high
|
|
depends_on: [T01]
|
|
```
|
|
|
|
Document in `citation-engine/README.md`:
|
|
|
|
- **Local dev** — `link:../citation-engine` (sibling checkout layout).
|
|
- **Post-publish** — `pnpm add @citation-evidence/engine` (registry TBD).
|
|
|
|
Review and stabilize `package.json` `exports`:
|
|
|
|
```json
|
|
{
|
|
".": "./src/engine/index.ts",
|
|
"./shared": "./src/shared/index.ts"
|
|
}
|
|
```
|
|
|
|
Confirm TypeScript consumers can resolve both entry points without deep imports
|
|
into `src/`. Add `types` conditions or subpath exports only if a consumer
|
|
repo hits resolution errors during `CE-WP-0009`.
|
|
|
|
**Acceptance:** README has copy-paste install snippets for umbrella and one
|
|
sister repo placeholder (`evidence-anchor`).
|
|
|
|
---
|
|
|
|
## T03 — SharedContracts sync runbook
|
|
|
|
```task
|
|
id: CENG-WP-0002-T03
|
|
status: done
|
|
priority: high
|
|
depends_on: [T01]
|
|
```
|
|
|
|
`citation-evidence/wiki/SharedContracts.md` remains the **authoritative**
|
|
contract. `citation-engine/wiki/SharedContracts.md` is a conformance copy for
|
|
enum tests (`evidence-link.test.ts`).
|
|
|
|
Write a short runbook (in `citation-engine/README.md` or `wiki/README.md`):
|
|
|
|
1. Contract change lands in umbrella `wiki/SharedContracts.md`.
|
|
2. Copy/sync to `citation-engine/wiki/SharedContracts.md`.
|
|
3. Update runtime enums/types in `src/shared/` if needed.
|
|
4. Run `pnpm test` in both repos.
|
|
|
|
**Acceptance:** runbook exists; `evidence-link.test.ts` path to local
|
|
`wiki/SharedContracts.md` is documented.
|
|
|
|
---
|
|
|
|
## T04 — Publish readiness (deferred until registry exists)
|
|
|
|
```task
|
|
id: CENG-WP-0002-T04
|
|
status: done
|
|
priority: low
|
|
depends_on: [T01, T02]
|
|
```
|
|
|
|
Prepare for first registry publish when a host is chosen (npm, GitHub Packages,
|
|
private Verdaccio, etc.):
|
|
|
|
- Decide `private: false` vs scoped private package.
|
|
- Add `files` whitelist (`src/`, `wiki/`, `README.md`, `LICENSE`).
|
|
- Optional: `tsc` emit to `dist/` if consumers cannot consume TypeScript
|
|
sources directly (decide based on ADR-0002 choice and first consumer).
|
|
- Versioning policy: semver from `0.1.0`; breaking contract changes bump minor
|
|
or major per `SharedContracts.md` § change process.
|
|
- CI publish step stub (document only — no registry credentials in repo).
|
|
|
|
**Acceptance:** a "Publishing checklist" section in README; package is
|
|
structurally publishable even if no publish has occurred yet.
|
|
|
|
---
|
|
|
|
## Relationship to other workplans
|
|
|
|
| Workplan | Role |
|
|
|----------|------|
|
|
| `CENG-WP-0001` | Extraction — **done** |
|
|
| `CE-WP-0009` | Umbrella consumes engine via `link:` — **done** |
|
|
| `CENG-WP-0002` | Distribution strategy and publish prep — this file |
|
|
| Future `EANCH-WP-0002`, etc. | Sister-repo extractions depend on engine install story from T02 | |