docs(scope): fill in SCOPE.md — resolves C-30 staleness
Replace the unfilled template with the umbrella's actual boundary: app/viewer/session + anchoring/evidence/binders in scope; headless ingest (evidence-source) and contracts (citation-engine) out of scope. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
parent
89e6236554
commit
cf57a9bb50
1 changed files with 50 additions and 66 deletions
116
SCOPE.md
116
SCOPE.md
|
|
@ -8,130 +8,114 @@
|
||||||
|
|
||||||
## One-liner
|
## One-liner
|
||||||
|
|
||||||
<!-- Describe the purpose of this repository in one precise sentence. -->
|
Document-centered evidence workspace — the umbrella app that lets a user open
|
||||||
<!-- Example: "Provides a lightweight event router for Kubernetes-native systems." -->
|
documents, capture selections as durable citations, and organize them into
|
||||||
|
evidence sets and binders.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Core Idea
|
## Core Idea
|
||||||
|
|
||||||
<!-- What is the main capability or idea behind this repository? -->
|
Turn a pile of source documents into traceable evidence. A user opens a
|
||||||
<!-- What problem does it try to solve? -->
|
document, highlights a passage, and the app captures a durable, re-resolvable
|
||||||
|
selector plus the surrounding context. Those captures become citations that can
|
||||||
|
be linked, grouped into evidence sets, and exported. During the umbrella-first
|
||||||
|
MVP the app also hosts subsystems that are being extracted into their own repos
|
||||||
|
as they stabilize.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## In Scope
|
## In Scope
|
||||||
|
|
||||||
<!-- What this repository is responsible for. -->
|
- The application shell, viewer, and session management (upload, sample
|
||||||
<!-- Be explicit and concrete. -->
|
sessions, export/re-import ZIP)
|
||||||
|
- Anchoring: creating and resolving selectors against document representations
|
||||||
-
|
- Evidence capture, evidence links, evidence sets, citation cards, and binders
|
||||||
-
|
- Viewer URL resolution and blob-vs-fixture policy for uploaded PDFs
|
||||||
-
|
- The source ↔ anchor round-trip integration contract
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Out of Scope
|
## Out of Scope
|
||||||
|
|
||||||
<!-- What this repository deliberately does NOT do. -->
|
- Headless document ingest / fingerprinting / extraction — owned by
|
||||||
<!-- This is often more important than "In Scope". -->
|
`evidence-source` (consumed here via the `@source` façade)
|
||||||
|
- The shared domain model and engine services — owned by `citation-engine`
|
||||||
-
|
(`@citation-evidence/engine`)
|
||||||
-
|
- Persisting evidence to a server backend (MVP is browser/session-local)
|
||||||
-
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Relevant When
|
## Relevant When
|
||||||
|
|
||||||
<!-- When should someone consider using or exploring this repository? -->
|
- You are working on the end-user evidence workflow (capture, link, organize)
|
||||||
|
- You are changing the viewer, session lifecycle, or app UI
|
||||||
-
|
- You need the integration surface that ties ingest, anchoring, and binders together
|
||||||
-
|
|
||||||
-
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Not Relevant When
|
## Not Relevant When
|
||||||
|
|
||||||
<!-- When should someone ignore this repository? -->
|
- You need to change how documents are ingested/extracted (see `evidence-source`)
|
||||||
|
- You need to change the `Document`/selector/evidence contracts (see `citation-engine`)
|
||||||
-
|
|
||||||
-
|
|
||||||
-
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Current State
|
## Current State
|
||||||
|
|
||||||
<!-- Rough indication of maturity. No strict format required. -->
|
- Status: active
|
||||||
|
- Implementation: substantial (umbrella-first MVP functional; 125-test suite green)
|
||||||
|
- Stability: evolving (subsystems being extracted into standalone repos)
|
||||||
|
- Usage: internal / personal (MVP)
|
||||||
|
|
||||||
- Status: <!-- e.g. concept / experimental / active / stable / deprecated -->
|
The PDF ingest slice was extracted into `evidence-source` (ESRC-WP-0001) and is
|
||||||
- Implementation: <!-- e.g. idea / partial / substantial / complete -->
|
now consumed across the repo boundary. No umbrella-owned workplans are currently
|
||||||
- Stability: <!-- e.g. unstable / evolving / stable -->
|
open; active change is driven from the extracted subsystem repos.
|
||||||
- Usage: <!-- e.g. none / personal / internal / production -->
|
|
||||||
|
|
||||||
<!-- Add any notes that help set expectations. -->
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## How It Fits
|
## How It Fits
|
||||||
|
|
||||||
<!-- Where does this repository sit in the bigger picture? -->
|
- Upstream dependencies: `citation-engine` (contracts + engine), `evidence-source` (PDF ingest)
|
||||||
|
- Downstream consumers: end users of the evidence workspace
|
||||||
- Upstream dependencies:
|
- Often used with: `citation-engine`, `evidence-source`
|
||||||
- Downstream consumers:
|
|
||||||
- Often used with:
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Terminology
|
## Terminology
|
||||||
|
|
||||||
<!-- Terms that are important to understand this repo. -->
|
- Preferred terms: citation, selector, evidence set, binder, representation
|
||||||
<!-- Especially useful if naming differs from other repos. -->
|
- Also known as: "the umbrella" / "the app"
|
||||||
|
- Potentially confusing terms: "source" (here means the app's `src/source`
|
||||||
- Preferred terms:
|
façade over `evidence-source`, not raw source documents)
|
||||||
- Also known as:
|
|
||||||
- Potentially confusing terms:
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Related / Overlapping Repositories
|
## Related / Overlapping Repositories
|
||||||
|
|
||||||
<!-- List repositories that have similar or adjacent responsibilities. -->
|
- `citation-engine` — shared domain model and engine services this app builds on
|
||||||
<!-- Helps detect duplication and navigate the ecosystem. -->
|
- `evidence-source` — headless PDF ingest extracted from this repo's `src/source`
|
||||||
|
|
||||||
- <repo-name> — <!-- how it relates -->
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Getting Oriented
|
## Getting Oriented
|
||||||
|
|
||||||
<!-- If someone decides to look deeper, where should they start? -->
|
- Start with: `README.md`, then `wiki/ArchitectureOverview.md`
|
||||||
|
- Key files / directories: `src/app/` (shell + sessions), `src/anchor/`
|
||||||
- Start with:
|
(selectors), `src/binder/`, `src/work/` (session/engine context)
|
||||||
- Key files / directories:
|
- Entry points: the Vite app (`pnpm dev`); `tests/integration/` for end-to-end contracts
|
||||||
- Entry points:
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Provided Capabilities
|
## Provided Capabilities
|
||||||
|
|
||||||
<!-- What can this repo's domain provide to other domains on request? -->
|
<!-- The reusable ingest capability now lives in evidence-source's registry.
|
||||||
<!-- Each capability block is parsed by the state-hub capability catalog ingest. -->
|
This umbrella currently exposes no standalone capability of its own. -->
|
||||||
<!-- Remove the examples and add your own, or leave empty if none. -->
|
|
||||||
|
|
||||||
<!--
|
|
||||||
```capability
|
|
||||||
type: infrastructure
|
|
||||||
title: Example capability title
|
|
||||||
description: What this capability provides, in one or two sentences.
|
|
||||||
keywords: [keyword1, keyword2, keyword3]
|
|
||||||
```
|
|
||||||
-->
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Notes
|
## Notes
|
||||||
|
|
||||||
<!-- Anything else worth knowing. Keep it short. -->
|
Subsystems graduate from `src/` into sibling repos as they stabilize
|
||||||
|
(`citation-engine`, `evidence-source`); the umbrella keeps app/viewer/session
|
||||||
|
concerns and the cross-subsystem integration tests.
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue