docs(readme): rewrite around concerns octad (V-L1-A2 / #20)#99
Merged
Conversation
Closes #20. ADR-0004 made the concerns octad canonical; the README still led with the modalities table. This rewrite: * Replaces the "Eight Modalities" table with an "Eight Concerns" table mapped to (question, sidecar table, code module, tier) per the issue's acceptance criteria. * Recasts the drift section as **symptoms of Constraints-violation across modalities** rather than a free-standing taxonomy. The eight categories are listed with their default thresholds and a pointer to ADR-0003 for the (input, distance, threshold) triples. * Reframes Tier 2 modalities (graph, vector, tensor, semantic, document, spatial) as *overlay representations* — alternative shapes the same entity is projected into for a specific query workload, independent of which concerns are active. The Simulation concern is also Tier 2 per ADR-0006. * Updates the architecture diagram so Tier 1 boxes are labelled by concern (provenance log, lineage DAG, temporal versions, access policies, constraint/drift index) and Tier 2 boxes by modality (graph index, vector HNSW, tensor ndarray, semantic CBOR, document Tantivy, spatial R-tree), with simulation branches called out separately per ADR-0006. * Adds a "Building and Running" section that names the canonical build paths from ADR-0009: cargo for dev (MSRV 1.85), Containerfile for ops. The experimental Nix/Guix/devcontainer paths are acknowledged but flagged as such. * Cross-references the shipping implementations: V-L1-E2 (#49) Temporal drift detector as the first ADR-0003 category, V-L2-P1 (#50) `verisimiser gc` for `[retention]` enforcement, the provenance threat model (#25), and ADRs 0003/0004/0005/0006/0007 for the binding decisions. `ROADMAP.adoc` Phase 0 / Phase 1 also rewritten: each Tier 1 bullet is now per-concern (Provenance / Lineage / Temporal / AccessControl / Constraints), with the eight drift categories tracked as Constraints sub-items so the one shipped today (Temporal) and the seven remaining (Structural / Semantic / Statistical / Referential / Provenance / Spatial / Embedding) are visible from one place. No code change. Tests unaffected. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
hyperpolymath
force-pushed
the
v-l1-a2-readme-concerns-octad
branch
from
ba3e66d to
c6d9a19
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #20. README and ROADMAP rewritten around the concerns octad after ADR-0004 made it canonical.
README.adoc— "Eight Concerns" table with (question, sidecar, module, tier); drift section recast as symptoms of Constraints-violation across modalities; Tier 2 reframed as overlay representations; architecture diagram labelled by concern (Tier 1) and modality (Tier 2); new "Building and Running" section names cargo + Containerfile per ADR-0009.ROADMAP.adoc— Phase 0 / Phase 1 rewritten per-concern; eight ADR-0003 drift categories tracked as Constraints sub-items so the one shipped today (Temporal, V-L1-E2: implement Temporal drift detector (first category) #49) and the seven remaining are visible together.No code change; the rewrite is pure docs.
Test plan