coulomb/citation-evidence
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Establish shared-contracts home, dependency map, MVP workplans, and umbrella-first strategy

Browse Source 
- INTENT.md: declare umbrella as the home for shared contracts; document
  umbrella-first MVP decision (code lives here until subsystems stabilize)
- wiki/SharedContracts.md: vocabulary, state enums, relation types,
  selector taxonomy, event vocabulary, viewer adapter contract,
  canonical text normalization, rect-registry contract
- wiki/DependencyMap.md: allowed dependency edges; folder layout +
  lint-rule strategy during umbrella-first phase
- history/2026-05-24-initial-assessment.md: alignment review, technical
  risks, and the umbrella-first pivot rationale
- workplans/CE-WP-0001..0004: four ralph-compatible workplans covering
  foundations, PDF review slice, form binding + visual guide, and
  citation card export — implementing PRD §20 end-to-end

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Bernd Worsch
2026-05-24 16:42:25 +02:00
parent bc95737e6a
commit d06a456c2a
9 changed files with 1597 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
INTENT.md
View File

@@ -189,6 +189,59 @@ This repository should be:
---
## Home for Shared Contracts
This repository is the **single home for everything the sister repos must
agree on**. The canonical documents live in `wiki/`:
* `wiki/ProductRequirementsDocument.md` — what the product does
* `wiki/ArchitectureOverview.md` — how the subsystems compose
* `wiki/SharedContracts.md` — vocabulary, state enums, relation types, selector taxonomy, event types, viewer adapter contract, canonical text normalization
* `wiki/DependencyMap.md` — which subsystem may depend on which
* `docs/decisions/` — ADRs that resolve ambiguities and bind the contract
Sister repos (`citation-engine`, `evidence-anchor`, `evidence-source`,
`citation-work`, `evidence-binder`) defer to these documents. When their
own `INTENT.md` files mention "shared contracts", they mean the documents
listed above.
Changes to shared contracts happen here, not in the sister repos.
---
## MVP Strategy — Umbrella-First (decided 2026-05-24)
**The MVP lives entirely in this repository before being segmented into the
sister repos.** This is a deliberate trade-off: fewer interface decisions up
front, more refactoring later when extraction happens.
The reasoning:
1. The architectural boundaries documented in the sister INTENT files are
hypotheses. We do not yet know which ones will hold up under real product
pressure.
2. Coordinating six repos with no working code is expensive. Coordinating one
repo with working code is cheap.
3. Interfaces designed in advance of implementation tend to be wrong.
4. Extracting working code into a new repo is a known, bounded refactor.
Reshaping a premature interface while implementing against it is not.
Concretely:
* All MVP source code lives under `citation-evidence/src/`, partitioned by
future-repo names (`shared/`, `engine/`, `anchor/`, `source/`, `work/`,
`binder/`, `app/`).
* The `DependencyMap.md` rules are enforced by lint rules on these folders.
* The five sister repos remain INTENT-only during MVP — they document the
intended boundary, not current code.
* When a subsystem's interface stabilizes (typically after the MVP scenario
has run end-to-end at least once), its `src/<repo-name>/` slice extracts
to the sister repo.
This INTENT will be updated when extraction happens.
---
## Success Criteria
The repository is successful when it allows a developer or agent to understand, run, and extend the citation-evidence system as an integrated product.