generated from coulomb/repo-seed
tegwick
85a562b2a1
Verify sibling citation-engine checkout, link dependency resolution, toolchain, and absence of stale in-repo engine copies. Prints actionable fix hints when the installation layout is wrong.
80 lines
3.3 KiB
Markdown
80 lines
3.3 KiB
Markdown
# citation-evidence
|
|
|
|
A document-centered evidence workspace for capturing, managing, presenting,
|
|
and re-opening citations. The umbrella over the six-package design described
|
|
in `INTENT.md` and `wiki/ArchitectureOverview.md`.
|
|
|
|
Shared types and engine services live in the extracted
|
|
[`@citation-evidence/engine`](../citation-engine/) package (`link:../citation-engine`).
|
|
Remaining partitions stay under `src/` until each subsystem extracts.
|
|
|
|
## Documentation
|
|
|
|
| Where | What |
|
|
|------------------------|---------------------------------------------------------|
|
|
| `INTENT.md` | Project intent, scope, the umbrella-first decision |
|
|
| `wiki/` | PRD, Architecture, SharedContracts, DependencyMap |
|
|
| `docs/decisions/` | ADRs (architecturally significant decisions) |
|
|
| `workplans/` | Ralph-driven workplans that implement the MVP slice |
|
|
| `history/` | Time-stamped assessments and post-mortems |
|
|
|
|
The canonical contracts are in [`wiki/SharedContracts.md`](wiki/SharedContracts.md);
|
|
the partition boundaries are in [`wiki/DependencyMap.md`](wiki/DependencyMap.md).
|
|
Both are referenced from every workplan and from each sister repo's INTENT.md.
|
|
|
|
## Repository layout
|
|
|
|
Requires sibling checkout: `../citation-engine` (see `package.json` `link:` dep).
|
|
|
|
```
|
|
src/
|
|
anchor/ # selector creation/resolution, viewer adapter contract → becomes evidence-anchor
|
|
source/ # ingest, fingerprint, extraction, recovery → becomes evidence-source
|
|
binder/ # evidence-to-target binding, visual guide → becomes evidence-binder
|
|
work/ # review UI (sidebar, viewer shell) → becomes citation-work
|
|
app/ # the reference workspace shell → stays in citation-evidence
|
|
```
|
|
|
|
The dependency-edge rules between partitions are enforced by ESLint via
|
|
`eslint-plugin-boundaries` (see `eslint.config.js`). Extraction to a sister
|
|
repo is intended to be a `git mv` plus a `package.json` cut — nothing more.
|
|
|
|
## Sister repos
|
|
|
|
Peers under `~/`:
|
|
|
|
- [`~/citation-engine`](../citation-engine/) — **extracted** shared model + engine (`@citation-evidence/engine`)
|
|
- [`~/evidence-anchor`](../evidence-anchor/) — selectors + adapter contract
|
|
- [`~/evidence-source`](../evidence-source/) — ingest, representation, recovery
|
|
- [`~/evidence-binder`](../evidence-binder/) — binding, visual guide, rect registry
|
|
- [`~/citation-work`](../citation-work/) — review UI surfaces
|
|
|
|
## Dev workflow
|
|
|
|
Requirements: Node 20 LTS (see `.nvmrc`) and `pnpm` 9.
|
|
|
|
```bash
|
|
# citation-engine must be checked out next to this repo (../citation-engine)
|
|
make check-install # diagnose layout problems before install
|
|
pnpm install
|
|
pnpm dev # vite dev server (once src/app/ has a real entry)
|
|
pnpm test # vitest one-shot
|
|
pnpm test:watch
|
|
pnpm lint # eslint with boundary rules
|
|
pnpm typecheck # tsc --noEmit
|
|
pnpm build # production bundle
|
|
```
|
|
|
|
## Workplans (Ralph)
|
|
|
|
Workplans drive incremental implementation through the ralph loop. The harness
|
|
lives in `~/ralph-workplan/`; see `docs/mvp-workplans-index.md` for the active list
|
|
and ordering.
|
|
|
|
```bash
|
|
/ralph-workplan workplans/CE-WP-0001-foundations.md
|
|
```
|
|
|
|
The loop self-retires when every task in the file has `status: done` and the
|
|
workplan's frontmatter `status: done`.
|