{"path":"research/execution-plan-clarification-first-roadmap.md","content":"# Execution Plan: Clarification-First Deliberus\n\n**Date**: April 3, 2026\n**Purpose**: Translate the current philosophical/product roadmap into an executable multi-phase program grounded in the existing Deliberus codebase and documentation.\n\n**Status**: This is not a speculative greenfield plan. It is written against the currently live Deliberus system: extraction, claim pages, correction UX, CQ generation, QBAF badges, auto-connect, feed modes, and the current ontology frontier.\n\n---\n\n## 0.5. Current Implementation Status (Apr 3, 2026)\n\nThis document is now partially cashed out in code. The roadmap itself still stands, but the leading edge is no longer hypothetical.\n\n### Implemented so far\n\n- **Execution/planning layer written and sequenced**\n  The roadmap itself exists and has already been used as the basis for implementation ordering.\n\n- **Phase 1 / Tranche A substantially implemented**\n  Claim-level clarification exists in the live code:\n  - users can load contested concepts for a claim\n  - users can clarify a contested term\n  - clarification creates a first-class definitional claim\n  - the clarification is linked back into the target claim's concept usage\n  - extraction pages now surface an earlier interpretation checkpoint for contested source usages, reusing the same definitional-claim machinery at the claim level\n  - the landing page now runs a lightweight preflight for text and URL input, surfacing the 1-3 most load-bearing ambiguities before full extraction\n  - the preflight now bifurcates correctly by source type:\n    - authored text asks \"what do you mean here?\"\n    - external material asks \"which reading best fits what the source seems to mean here?\"\n  - sense options now come from shared graph memory when available and fall back to pipeline-detected provisional senses for first-time sources\n  - preflight clarifications now persist into the extraction itself as definitional claims rather than disappearing as local UI state\n  - uploaded documents now participate in the same provenance-aware preflight loop: they default to source-reading prompts, while a contextual \"I wrote this\" correction switches the prompt to the user's own intended meanings\n\n- **Phase 2 / Tranche B meaningfully implemented, but not finished**\n  Concept memory is no longer purely local:\n  - concept usage counts and sense counts are aggregated\n  - concept detail API exists\n  - concept pages exist\n  - explicit definition claims are now visible as reusable graph memory, not only as hidden backend structure\n  - claim and extraction pages now link outward to shared concept state\n  - concept pages and APIs now surface emergent lifecycle states like underdefined, emerging, bifurcated, fragmented, and locally stable\n  - concept memory now includes a next-step diagnosis instead of only raw sense counts\n  - a browseable `/concepts` index now exposes that shared concept layer across the graph, not only one term at a time\n\n- **Phase 3 / Tranche C lightly but genuinely started**\n  Recursive deepening is still early, but no longer untouched:\n  - decomposition is no longer treated as only a value-premise affordance\n  - decomposition now inherits parent claim type\n  - decomposition provenance is preserved more faithfully\n  - claim pages now surface decomposition structure more explicitly\n  - the backend now scores whether claims still look bundled rather than atomic-for-now\n  - extraction pages now surface a first \"Deepen Next\" list of the strongest decomposition candidates within one source\n  - claim pages now reuse backend decomposition guidance to seed a non-blank starting structure, so recursive deepening is less blind than a raw empty textarea\n  - template-only scaffold submissions are rejected, so guided decomposition does not quietly create empty graph noise\n  - parent claims now expose a decomposition state, so a mother claim can summarize whether its current direct substructure is not yet decomposed, partially deepened, still bundled downstream, or coherent-for-now\n  - that parent-state layer now notices when direct subclaims look atomic-for-now but the downstream frontier remains bundled, so “coherent for now” is no longer a false local optimum\n  - critical-question polarity claims now also receive decomposition-readiness metadata, so the CQ layer is beginning to participate in the same recursive-deepening loop instead of remaining a static sorry marker layer\n\n- **Phase 6 lightly but genuinely started**\n  The feed is still immature, but it now begins to reflect clarification/deepening needs rather than only activity:\n  - `needs-help` is no longer only unanswered-CQ density\n  - it now also surfaces claims that still look bundled and likely want decomposition next\n  - it can now descend one layer deeper and surface bundled CQ polarity claims when that is the clearest next deepening move\n  - when decomposition is the clearest next move, the feed can now route directly into focused deepening rather than only generic claim inspection\n\n### Not yet implemented\n\n- file-upload and full voice-to-sense-selection continuity at the top-level input layer\n- stronger merge/split governance for concept senses\n- deeper recursive decomposition of CQ polarity claims, reasoning traces, and mother claims\n- revision-history / supersession semantics\n- feed evolution into a true clarification work queue\n- shared external-text inquiry workbench\n- worldview / bridging layers grounded in earned data\n\n### Practical reading of the roadmap right now\n\nThe roadmap is still correct in sequence:\n\n1. Clarification first\n2. Shared concept memory second\n3. Recursive deepening third\n4. Larger social / bridging / institutional ambitions later\n\nWhat has changed is only that the first three steps are no longer all future tense. Step 1 is now real even at the landing route for text/URL input, Step 2 is underway in earnest, Step 3 has its first product-visible footholds, and Step 6 has a very early but meaningful precursor in the feed.\n\n---\n\n## 0. Document Lineage and Why This Exists\n\nThis execution document is not meant to replace the higher-level philosophy docs. It is the implementation-facing continuation of them.\n\nIts role is:\n\n- to translate the archive's current frontier into ordered product phases\n- to prevent implementation drift toward whatever is easiest to code next\n- to make explicit why some attractive ideas must wait until prerequisite epistemic structure exists\n- to preserve the archive's documentation philosophy: strategy and ontology live above code, but code should cash them out in visible product behavior\n\nThis plan should therefore be read alongside, not instead of:\n\n- [vision.md](../vision.md) — the soul of the project, the core dialectic, semantic disambiguation, no-copout axioms, one shared graph\n- [analysis-and-attunement.md](../analysis-and-attunement.md) — why analysis serves attunement, not the reverse\n- [frontier.md](../frontier.md) — what the live edge currently is\n- [ux-principles.md](../ux-principles.md) — product principles already distilled from the archive\n- [conceptual-threads.md](../conceptual-threads.md) — the broader network of tensions this roadmap must honor\n- [semantic-disambiguation-and-concept-tracking.md](semantic-disambiguation-and-concept-tracking.md) — the most direct ancestor of Phases 1-2\n- [disambiguation-ux-and-voice-first-contribution.md](disambiguation-ux-and-voice-first-contribution.md) — the main UX argument for why disambiguation is the key micro-contribution\n- [self-similar-decomposition-and-claim-ontology.md](self-similar-decomposition-and-claim-ontology.md) — the main ontology argument for Phase 3\n- [single-player-utility.md](single-player-utility.md) — why the single-player/object-level loop must work before grand social ambition\n- [feed-algorithm-design.md](feed-algorithm-design.md) — why the feed should become epistemic work allocation, not engagement theater\n- [session7-deep-review-and-strategic-assessment.md](session7-deep-review-and-strategic-assessment.md) — especially the analysis-attunement framing and the anti-meta testing principle\n- [session10-empirical-collaboration-and-atomization-frontier.md](session10-empirical-collaboration-and-atomization-frontier.md) — the recent shift toward empirical object-level testing of decomposition depth\n- [david-deutsch-beginning-of-infinity-and-deliberus.md](david-deutsch-beginning-of-infinity-and-deliberus.md) — why explanatory improvement and criticism matter more than foundational rhetoric\n\nIn short: this document exists to answer, with discipline, \"what should be built next, in what order, and why exactly that order?\"\n\n---\n\n## 1. Program-Level Thesis\n\nThe next era of Deliberus should not optimize for \"more extraction\" in the abstract.\n\nThe current product already proves:\n\n- text, URL, and PDF ingestion\n- extraction of claim structure\n- scheme classification and CQ generation\n- claim-level correction flows\n- graph persistence\n- similarity linking and early cross-extraction connection\n- feed ranking by epistemic opportunity rather than engagement\n\nWhat has **not** yet been proven is the deeper claim:\n\n- that Deliberus helps people state more exactly what they mean\n- that it helps them see where disagreement is semantic, evidential, structural, or genuinely deep\n- that it helps structure become sharper over time rather than merely more plentiful\n\nSo the execution program must be oriented around one primary transition:\n\n**Deliberus must move from structure extraction to clarification, disambiguation, and recursive deepening.**\n\n---\n\n## 2. What Already Exists and Must Be Preserved\n\nThe execution plan assumes the following are already real product assets and should be treated as foundations rather than rethought from scratch:\n\n### Backend foundations\n\n- [api.py](../../deliberus/api.py): ingestion, extraction orchestration, claim endpoints, CQ endpoints, correction endpoints, voting, feed endpoints\n- [models.py](../../deliberus/extraction/models.py): `ClaimBase`, claim types, relationship ontology, CQ models\n- [store.py](../../deliberus/graph/store.py): graph persistence for claims, relationships, contested concepts, questions, CQ polarity claims\n- [correction_pipeline.py](../../deliberus/extraction/correction_pipeline.py): scheme detection and CQ generation on user-contributed edges\n- [qbaf.py](../../deliberus/graph/qbaf.py): gradual semantics and badge computation\n- [feed.py](../../deliberus/feed.py): epistemic feed ranking modes\n\n### Frontend foundations\n\n- [landing page input flow](../../web/src/routes/+page.svelte): text / URL / PDF entry\n- [extraction detail page](../../web/src/routes/extraction/[id]/+page.svelte): argument structures, claims, contested concepts\n- [claim page](../../web/src/routes/claim/[id]/+page.svelte): voting, decomposition, evidence addition, CQ answering, neighborhood viewing\n\n### Philosophical foundations\n\n- one node type: Claim\n- definitions are first-class, not metadata\n- nothing is permanently atomic\n- extraction should be tested on object-level texts, not self-referential meta material\n- the graph should support clarification, not replace human thought with pseudo-understanding\n\n### Documentary foundations\n\nThe crucial thing to preserve is not just code paths, but the archive's hard-won ordering of priorities.\n\nMost relevant high-level commitments already settled elsewhere:\n\n- [vision.md](../vision.md) says the analysis serves attunement; this means \"more structure\" is not enough unless it increases understanding\n- [vision.md](../vision.md) and [semantic-disambiguation-and-concept-tracking.md](semantic-disambiguation-and-concept-tracking.md) already establish that definitions are graph structure, not side metadata\n- [frontier.md](../frontier.md) identifies practical atomization and voice-first disambiguation as live frontiers, not optional polish\n- [single-player-utility.md](single-player-utility.md) already argues that Deliberus must first be useful to one person thinking through one hard thing\n- [feed-algorithm-design.md](feed-algorithm-design.md) already rejects engagement logic and points toward epistemic work selection\n\nThis roadmap assumes those arguments have largely been won. The task here is sequencing the implementation that follows from them.\n\n---\n\n## 3. Non-Negotiable Constraints\n\nThese govern all phases.\n\n1. **Ontology before ornament.**\n   If a phase adds expressive UI without improving graph meaning, it is mis-sequenced.\n\n2. **Clarification before spectacle.**\n   No major worldview lens or bridging theatrics before concept disambiguation and recursive decomposition materially work.\n\n3. **Object-level before meta-level.**\n   Product testing should prioritize external substantive texts and real dilemmas, not texts about Deliberus or argumentation theory.\n\n4. **Single-player before synchronous social complexity.**\n   The product should deliver epistemic value to one person working with one difficult text or one difficult belief before expecting multi-user choreography.\n\n5. **Revision should be preserved cheaply where possible, but never at the expense of clarification velocity.**\n   Silent overwrite is undesirable, but historical preservation must not obstruct the product's ability to sharpen claims and structures quickly.\n\n6. **No interpassive pseudo-understanding.**\n   AI can scaffold, extract, suggest, compare, and provoke. It must not make the user feel that clarification happened if the user did not actually clarify.\n\n7. **Explanatory improvement over foundational posturing.**\n   In the Deutschian sense, the relevant question is whether the system helps produce better, harder-to-vary explanations and better criticism, not whether it claims to have reached indubitable bedrock.\n\n8. **Cheap historical preservation, expensive workflow friction.**\n   Versioning is desirable when cheap, but not if it slows the clarification loop or makes every local refinement ceremonious.\n\n9. **Empirical object-level testing over abstract comfort.**\n   Product truth must be sought on external texts, real normative disagreements, and actual user attempts at clarification and decomposition. Internal coherence of the theory is not enough.\n\n---\n\n## 3.5. Why This Roadmap and Not the More Tempting Alternatives\n\nThere are several plausible-looking directions the project could take next that would be easier to justify emotionally than epistemically. This section names them explicitly so they do not keep silently steering implementation.\n\n### Why not \"just make extraction much better\" first?\n\nBecause extraction quality alone does not prove Deliberus's real thesis.\n\nThe archive's core ambition is not merely:\n\n- more claims\n- better claim grouping\n- prettier graph output\n\nIt is:\n\n- better clarification\n- better diagnosis of disagreement\n- better decomposition of bundled reasoning\n- better possibility of attunement through structure\n\nImproving extraction is still necessary. But if extraction improves without clarification becoming first-class, the system risks becoming a more impressive parser for still-blurry thought.\n\n### Why not jump straight to worldview lenses and bridging?\n\nBecause before concept disambiguation and recursive deepening, those features would mostly be theater.\n\n[worldview-lenses.md](../worldview-lenses.md) is powerful, but it depends on real underlying data about:\n\n- operative definitions\n- load-bearing value differences\n- semantic vs evidential vs structural disagreement\n\nWithout that, \"worldview\" outputs become a tasteful flattening of disagreement rather than earned insight.\n\n### Why not prioritize social/community mechanics?\n\nBecause [single-player-utility.md](single-player-utility.md) and [ux-principles.md](../ux-principles.md) are right: if one person cannot get real value from Deliberus on one difficult text or belief, then social scale only magnifies weakness.\n\n### Why not build full revision/version infrastructure first?\n\nBecause the object to preserve historically is not yet evolving at the right locus.\n\nThe first duty is to make users actually produce clarifications and decompositions worth preserving. Versioning matters, but it should follow enough live refinement pressure to justify its weight.\n\n---\n\n## 4. Program Structure\n\nThe work breaks naturally into eight major phases.\n\nThe phases are not equally large. Some can overlap. But their order matters.\n\n### Phase 1: Clarification-First Input Loop\n\n**Implementation status**\nSubstantially implemented in the current codebase for claim pages, extraction pages, and the landing route's text/URL/document flow. The first short-authored-input path now exists: short authored questions/topics route to a read-only truth-graph conversational response with provisional structure rather than falling through source extraction. Uploaded documents now get a contextual provenance correction so a user can mark their own book/paper as authored rather than external source material. Raw/private draft persistence is now live too, and the same authored-input draft can continue across turns instead of restarting from scratch each time. Still incomplete for visible multi-turn history, richer follow-up prompts, and the confirmation/promotion layer that turns provisional authored structure into durable graph nodes and relations.\n\n**Goal**\nMake \"what do I actually mean?\" a first-class product action.\n\n**Why this is first**\nThis is the clearest mismatch between current product reality and the current frontier docs.\n\n**Primary documentary grounding**\n\n- [vision.md](../vision.md) §Semantic Disambiguation\n- [semantic-disambiguation-and-concept-tracking.md](semantic-disambiguation-and-concept-tracking.md)\n- [disambiguation-ux-and-voice-first-contribution.md](disambiguation-ux-and-voice-first-contribution.md)\n- [ux-principles.md](../ux-principles.md) on voice-first disambiguation and progressive disclosure\n- [session10-empirical-collaboration-and-atomization-frontier.md](session10-empirical-collaboration-and-atomization-frontier.md)\n- [truth-graph-evidence-system.md](truth-graph-evidence-system.md) on \"capture immediately, publish deliberately\" for short authored input\n\n**Core deliverables**\n\n- contested-concept detection on user-contributed input and claim-level interaction\n- sense selection or sense refinement as a first-class user action\n- definitional claims created from those clarifications\n- visible feedback that clarification changed interpretation\n- root-route lightweight preflight using scout-derived ambiguity hotspots rather than the full extraction pipeline\n- authored-vs-source phrasing split preserved at the first checkpoint instead of buried later in the product\n- preflight clarifications persisted into the stored extraction and graph rather than treated as disposable UI hints\n- mode-aware handling of short authored input: answer from the truth graph/background knowledge and derive private provisional structure before any durable graph write\n- lightweight confirmation from provisional authored structure into graph contribution\n- contextual provenance correction instead of a persistent settings panel, especially for user-authored PDFs/books versus external sources\n\n**Primary code surfaces**\n\n- `deliberus/api.py`\n- `deliberus/graph/store.py`\n- `web/src/routes/claim/[id]/+page.svelte`\n- later: `web/src/routes/+page.svelte`\n\n**Dependencies**\n\n- existing contested concept storage\n- existing claim page correction UX patterns\n\n**Why this comes before other attractive work**\n\n- before better feed logic, because the feed needs better signals\n- before worldview functionality, because worldview without definitions is blur\n- before heavy versioning, because first we need the right unit of refinement\n- before broad social tooling, because the single-user clarification loop must prove value first\n\n**Acceptance criteria**\n\n- a user can clarify what a contested term means in a specific claim\n- the clarification creates persistent graph structure\n- the claim page reflects the clarified sense\n- no existing extraction/correction workflows are broken\n- the user sees some immediate consequence of clarification rather than feeling they merely filled out metadata\n\n**Risks**\n\n- disambiguation reduced to superficial labeling\n- custom taxonomy pressure too early\n\n**Mitigation**\n\n- tie clarification to downstream graph effects\n- let senses emerge from graph usage whenever possible\n\n---\n\n### Phase 2: Definitional Graph and Concept Tracking\n\n**Implementation status**\nStarted in earnest, but still incomplete.\n\n**Goal**\nTurn clarification from a local interaction into reusable graph memory.\n\n**Primary documentary grounding**\n\n- [semantic-disambiguation-and-concept-tracking.md](semantic-disambiguation-and-concept-tracking.md)\n- [vision.md](../vision.md) §Semantic Disambiguation\n- [conceptual-threads.md](../conceptual-threads.md) on concept tracking as the solution\n- [ux-principles.md](../ux-principles.md) P18 / concept tracking\n\n**Core deliverables**\n\n- explicit graph links between claims and definitional claims\n- concept pages or concept-level APIs with accumulated senses\n- merge/split/stability semantics for senses\n- soft canonical clustering / merge-candidate governance that can treat very high-confidence near-duplicates as one operative cluster by default without destroying provenance or reversibility\n- claim-level visibility into which sense is currently operative\n\n**Primary code surfaces**\n\n- `deliberus/graph/store.py`\n- concept-related API endpoints\n- extraction and claim UI\n\n**Dependencies**\n\n- Phase 1 definitional-link flow\n\n**Why this comes next**\n\nPhase 1 lets a user clarify once. Phase 2 determines whether that clarification can become cumulative knowledge rather than isolated local cleanup.\n\n**Acceptance criteria**\n\n- repeated concept uses can accumulate reusable senses\n- future clarification options are graph-derived, not hardcoded\n- definitional structure can be queried and surfaced\n- the graph begins to expose \"we are using the same word differently\" as a recurring structural diagnosis\n- clustering can reduce manual dedup burden without silently collapsing genuinely different claims or senses\n\n**Risks**\n\n- over-engineered concept ontology too early\n- hidden coupling between extraction-time senses and user-added senses\n\n**Mitigation**\n\n- keep the representation minimal and graph-native\n- treat stability as emergent, not imposed\n\n---\n\n### Phase 3: Recursive Decomposition and Mother Claims\n\n**Implementation status**\nEarly foothold only. The philosophy is far ahead of the implementation here.\n\n**Goal**\nMake self-similar decomposition operational in the product.\n\n**Primary documentary grounding**\n\n- [self-similar-decomposition-and-claim-ontology.md](self-similar-decomposition-and-claim-ontology.md)\n- [vision.md](../vision.md) §The \"No Copout Axioms\" Conviction and the Apr 2026 self-dissolving representations addition\n- [depth.md](../depth.md)\n- [analysis-and-attunement.md](../analysis-and-attunement.md)\n- [session10-empirical-collaboration-and-atomization-frontier.md](session10-empirical-collaboration-and-atomization-frontier.md)\n- [david-deutsch-beginning-of-infinity-and-deliberus.md](david-deutsch-beginning-of-infinity-and-deliberus.md)\n\n**Core deliverables**\n\n- explicit handling of bundled claims\n- decomposition pathways from claims, evidence, CQ polarity claims, and reasoning blobs\n- visible distinction between atomic-for-now and genuinely clarified\n- better transitive strength flow for mother claims\n\n**Primary code surfaces**\n\n- extraction prompts/models\n- claim page\n- graph storage and edge semantics\n- QBAF aggregation assumptions\n\n**Dependencies**\n\n- Phases 1-2 make clarification more precise; decomposition depends on that\n\n**Why this does not come first**\n\nBecause decomposition without clarification often just produces smaller blurry units. The system first needs better leverage on meaning before it can responsibly go deeper on structure.\n\n**Acceptance criteria**\n\n- bundled claims can be structurally deepened\n- mother claim patterns become expressible and inspectable\n- edge/question strength can increasingly inherit from substructure\n- users can tell the difference between \"not yet decomposed\" and \"good enough for now\"\n- deeper decomposition improves evidential inspectability rather than merely increasing node count\n\n**Risks**\n\n- infinite recursion with little epistemic gain\n- user overwhelm\n\n**Mitigation**\n\n- decompose only when a meaningful burden of proof or ambiguity remains\n- preserve progressive disclosure\n\n---\n\n### Phase 4: Object-Level Shared Inquiry Workbench\n\n**Goal**\nSupport asynchronous shared work on one external text at a time.\n\n**Primary documentary grounding**\n\n- [single-player-utility.md](single-player-utility.md)\n- [session7-deep-review-and-strategic-assessment.md](session7-deep-review-and-strategic-assessment.md)\n- [session10-empirical-collaboration-and-atomization-frontier.md](session10-empirical-collaboration-and-atomization-frontier.md)\n- [david-deutsch-beginning-of-infinity-and-deliberus.md](david-deutsch-beginning-of-infinity-and-deliberus.md)\n\n**Core deliverables**\n\n- text-centered workspaces\n- side-by-side or staged comparison between human reading and Deliberus output\n- support for independent analysis plus Deliberus-assisted analysis\n- explicit unresolved sections, ambiguity zones, and load-bearing disagreements\n\n**Dependencies**\n\n- clarification and decomposition must already be meaningfully better\n\n**Why this waits until after 1-3**\n\nWithout clarification and recursive deepening, this would mainly become a place to compare shallow first-pass extractions. The intended workbench is not shared storage. It is shared inquiry.\n\n**Acceptance criteria**\n\n- a small group can use Deliberus to work on a real external text without collapsing into comments or vague agreement theater\n- multiple readings can coexist without pressure to prematurely converge\n- Deliberus can function as a third analytical participant rather than a decorative attachment\n\n---\n\n### Phase 5: Revision History and Epistemic Memory\n\n**Goal**\nPreserve intellectual development without blocking rapid refinement.\n\n**Primary documentary grounding**\n\n- [ux-principles.md](../ux-principles.md) P12 / deprecation over deletion\n- [lean-deliberus-analogies.md](lean-deliberus-analogies.md)\n- [semantic-disambiguation-and-concept-tracking.md](semantic-disambiguation-and-concept-tracking.md)\n- [feed-algorithm-design.md](feed-algorithm-design.md) on supersession and the organic redraw\n\n**Core deliverables**\n\n- superseded / refined / split / merged semantics\n- historical trace for claims and definitions\n- visible current-best version plus inspectable history\n\n**Dependencies**\n\n- Phases 1-4 create enough change pressure for versioning to matter\n\n**Why it is not earlier despite being desirable**\n\nHistorical preservation is good, but preserving the wrong or too-premature units beautifully is not the priority. Once definitional refinement and recursive deepening are real activities, versioning becomes naturally justified and easier to scope correctly.\n\n**Acceptance criteria**\n\n- users can improve a structure without erasing how that improvement happened\n\n---\n\n### Phase 6: Feed Evolution Into Clarification Work Queue\n\n**Goal**\nMake the feed surface where clarification and deepening are most needed.\n\n**Primary documentary grounding**\n\n- [feed-algorithm-design.md](feed-algorithm-design.md)\n- [conceptual-threads.md](../conceptual-threads.md) on the feed as truth-seeking infrastructure\n- [ux-principles.md](../ux-principles.md) P17 / feed as dashboard\n\n**Core deliverables**\n\n- stronger ranking based on unresolved concepts, blurry bundles, changed high-salience claims\n- watchlist / subscription mode\n- clearer reason strings per surfaced item\n\n**Dependencies**\n\n- earlier phases must supply richer signals\n\n**Why not sooner**\n\nWithout real clarification, concept tracking, decomposition, and revision data, the feed cannot yet surface the right work. It would mostly be a rearrangement of extracted content rather than a guide to the next epistemically valuable intervention.\n\n**Acceptance criteria**\n\n- the feed feels like epistemic work selection, not passive content browsing\n- surfaced reasons are intelligible enough that a user can decide what kind of contribution is needed next\n\n---\n\n### Phase 7: Bridging and Worldview Discovery From Earned Data\n\n**Goal**\nUse actual accumulated definitional, evaluative, and structural data to discover bridging and genuine fault lines.\n\n**Primary documentary grounding**\n\n- [worldview-lenses.md](../worldview-lenses.md)\n- [bridging.md](../bridging.md)\n- [convergence.md](../convergence.md)\n- [vision.md](../vision.md) on analysis serving attunement\n- [disambiguation-ux-and-voice-first-contribution.md](disambiguation-ux-and-voice-first-contribution.md) on bridging depending on disambiguation data\n\n**Core deliverables**\n\n- stronger bridging signals\n- bottom-up worldview clustering\n- parallax marking\n- richer disagreement diagnostics\n\n**Dependencies**\n\n- substantial real clarification and evaluation data\n\n**Why it must be earned**\n\nThis phase is where Deliberus risks becoming spiritually impressive but epistemically thin. It should only be built when the underlying graph can really distinguish semantic, evidential, structural, and value-ordering differences.\n\n**Acceptance criteria**\n\n- the system can distinguish semantic confusion from deeper disagreement with some credibility\n- some disagreements clearly dissolve under clarification\n- some disagreements clearly remain, and the system can explain why without flattening them\n\n---\n\n### Phase 8: Institutional / Corpus-Scale Modes\n\n**Goal**\nMake Deliberus useful as epistemic infrastructure for real groups handling real corpora.\n\n**Primary documentary grounding**\n\n- [vision.md](../vision.md)\n- [civilizational-vision.md](../civilizational-vision.md)\n- [single-player-utility.md](single-player-utility.md)\n- [session8-landing-page-and-civilizational-vision.md](session8-landing-page-and-civilizational-vision.md)\n\n**Core deliverables**\n\n- corpus-scale comparison\n- stakeholder / organization workflows\n- change tracking across texts and time\n- exportable institutional reasoning memory\n\n**Dependencies**\n\n- all earlier phases\n\n**Why this is late**\n\nInstitutional usefulness is downstream of epistemic integrity. If built too early, Deliberus risks collapsing into document processing, issue tracking, or deliberation theater for organizations that want outputs without the underlying clarification discipline.\n\n**Acceptance criteria**\n\n- organizations can use the system without flattening its epistemic character into mere document processing\n\n---\n\n## 5. Sequencing and Parallelism\n\nThe program should be understood as a sequence of epistemic dependencies, not just engineering dependencies.\n\nEach phase generates the kinds of data, user behavior, and graph structure that the next phase presupposes.\n\n### Strictly sequential dependencies\n\n- Phase 1 before Phase 2 in any meaningful sense\n- Phase 2 before serious bridging/worldview work\n- Phase 3 before claiming recursive decomposition is truly productized\n- Phase 4 before treating Deliberus as a serious shared inquiry environment\n- Phase 5 before large-scale collaborative refinement\n\n### Safe overlap\n\n- Phase 1 and early Phase 2 can overlap\n- Phase 3 decomposition work can begin while Phase 2 concept tracking is still maturing\n- Phase 6 feed refinement can start modestly as earlier signals improve\n- Phase 5 revision support can begin in cheap forms before full historical UI\n\n### Wrong overlaps to avoid\n\n- major worldview UX before concept disambiguation is credible\n- social/community mechanics before one-person usefulness is strong\n- institution-facing workflows before the epistemic core can survive real object-level use\n- elaborate historical machinery before actual refinement pressure exists\n\n---\n\n## 6. What Should Actually Be Implemented First\n\nThe first implementation tranche should be intentionally narrower than the whole roadmap.\n\n### Tranche A: Minimum viable clarification primitive\n\n**Status**\nImplemented.\n\nThis is the first code slice to implement immediately.\n\n**Includes**\n\n- claim-level endpoint(s) for retrieving contested concepts and candidate senses\n- claim-level endpoint(s) for clarifying a contested term\n- creation of definitional claims from that clarification\n- persistent graph link from clarification to claim\n- UI on claim pages for \"clarify what you mean by this term\"\n\n**Why this first**\n\n- it is the narrowest move that cashes out the current frontier\n- it does not require new ingestion architecture\n- it can reuse current correction UX patterns\n- it creates graph structure that later phases depend on\n- it is falsifiable quickly on real claims without needing FalkorDB-backed end-to-end graph verification locally\n\n### Tranche B: Reusable concept memory\n\n**Status**\nPartially implemented and clearly the active frontier.\n\nImmediately after Tranche A:\n\n- reuse clarified senses as selectable options\n- better concept APIs\n- concept-level state visible to the user\n\n### Tranche C: More serious recursive deepening\n\n**Status**\nStarted only in a bounded sense. Product cues are now broader, but the deeper recursive architecture is still ahead.\n\nAfter clarification exists:\n\n- detect bundles more aggressively\n- deepen CQ polarity claims and mother claims\n- improve UI affordances for recursive decomposition\n\n### Tranche D: Shared external-text iteration\n\n**Status**\nNot started in product form.\n\nOnly after A-C begin to hold:\n\n- preserve multiple readings of one external text\n- compare human reading with Deliberus output\n- support asynchronous improvement without premature convergence pressure\n\n---\n\n## 7. Detailed Execution Matrix\n\n### Phase 1 Matrix\n\n**Objective**\nClarification-first user loop\n\n**Current reality**\nClaim-page clarification and definitional-claim creation exist. Extraction pages surface an early interpretation checkpoint for contested source usages, and the root text/URL/document input route now runs a lightweight clarification preflight before full extraction. Document upload provenance is contextual rather than a permanent setting: default to external source, but let the user mark \"I wrote this\" when the document is their own work. The root route also now has the first short-authored-input dual path: answer with a truth-graph/background synthesis, derive provisional structure, and keep write status draft-only.\n\nThe newer refinement is on the presentation layer: the short-authored-input result now aims to be a beginner-readable first-take page rather than a truth-graph debugger. Internal terms like \"graph-backed\" and \"draft-only\" are removed from the main copy, redundant accordion previews of the user's unchanged sentence are avoided, and the page is organized around four visible questions: what Deliberus thinks first, what it is already seeing, what is still unclear, and what the best next step is.\n\nThe deeper next step is no longer merely \"confirmation before writing.\" The emerging model is one evolving graph with staged maturity rather than a hard split between conversation outside the graph and canonical structure inside it. Raw deliberation trace, draft structure, and canonical structure should coexist with explicit lifecycle/provenance semantics, so rough material can be saved immediately without dominating default retrieval. The first retrieval-layer slice of that model now exists in code: claim nodes can carry `maturity_stage` and `retrieval_weight`, new stored claims default to `candidate`, and default public truth-query/feed surfaces currently suppress `raw` / `draft` / `superseded` while honoring an explicit influence threshold. The next slice is live too: `/query` can persist a `deliberation_drafts` record containing the raw user turn, the assistant's first answer, context, synthesis, and heuristic promotion metadata, without making draft persistence a new failure point for the response itself. And the first continuity slice is now live as well: the same draft can be continued across turns, with the recent exchange fed back into the next synthesis rather than restarting from zero. The remaining gap is therefore visible multi-turn history, richer and more situation-aware follow-up prompts, clearer UI visibility of lifecycle, lineage-preserving promotion into shared graph structure, and automated promotion rules that let better-grounded structure increasingly carry more weight over time via clarification, decomposition, evidence, voting, and later QBAF/QEM/Bayesian evaluation. See [truth-graph-evidence-system.md](truth-graph-evidence-system.md).\n\n**Backend**\n\n- concept/sense query endpoints\n- clarification submission endpoint\n- definitional claim creation\n- graph link from definitional claim to target claim\n- selected-sense persistence on concept usage edges\n- default public retrieval guardrail for staged maturity on `/query` and feed surfaces\n- best-effort persistence of short-authored-input deliberation drafts, including raw turn trace, synthesis, and promotion hints\n- continuation of the same deliberation draft across turns, so authored-input clarification can accumulate instead of restarting\n\n**Frontend**\n\n- claim page concept cards\n- extraction-page interpretation checkpoint for contested source usages\n- root-route text/URL preflight card with graph-backed senses plus pipeline-detected fallback senses\n- one-click sense selection\n- optional custom clarification input\n- post-submit refresh of claim/extraction clarification state\n\n**Data model**\n\n- no new top-level node type\n- definitions remain claims\n- concept use edges can store selected/available sense metadata\n- authored-input work should likely stay inside one evolving graph, but with explicit lifecycle/provenance metadata rather than a separate shadow draft world\n- likely distinction: raw deliberation trace, draft structure, candidate structure, canonical/shared structure\n- first live slice: `Claim.maturity_stage` + `Claim.retrieval_weight`\n- second live slice: `deliberation_drafts` records for short-authored-input trace + synthesis + promotion state\n- third live slice: `/query` continuation over the same `deliberation_drafts` record, using recent turn trace as synthesis context\n- likely need for lineage edges or equivalent metadata (`derived_from`, `clarifies`, `responds_to`, `supersedes`) so refinement preserves history\n\n**Testing**\n\n- route existence\n- auth requirement for clarification submission\n- graph query shaping for claim concepts\n- graph query shaping for extraction clarification opportunities\n- creation of definitional claim and relation\n- local-safe mocked verification on MERIAN when graph infrastructure is not present\n- lifecycle-aware retrieval tests so newly captured rough material remains preservable without dominating first-pass results for other users\n- feed/query regression tests for `raw` / `draft` / `superseded` suppression and explicit retrieval-weight overrides\n- draft-persistence regression tests so `/query` still returns 200 when draft storage fails\n\n### Phase 2 Matrix\n\n**Objective**\nReusable concept tracking\n\n**Current reality**\nBasic concept memory, aggregation, concept pages, and explicit definition-claim surfacing exist; merge/split/stability semantics do not.\n\n**Backend**\n\n- aggregate concept senses across graph\n- merge/split support later\n- concept detail API\n\n**Frontend**\n\n- concept detail display\n- current-vs-alternative senses\n- links from claim to concept state\n\n**Testing**\n\n- aggregation of candidate senses across claims\n- stable display of current selected sense vs alternatives\n- no hardcoded ontology dependency for initial concept memory\n\n### Phase 3 Matrix\n\n**Objective**\nRecursive decomposition\n\n**Current reality**\nThe product now signals decomposition more honestly, preserves parent-type/provenance better, and has begun to extend decomposition guidance into the CQ polarity layer, but mother-claim and self-dissolving-representation behavior remain largely ahead.\n\n**Backend**\n\n- bundle-detection heuristics\n- decomposition helpers for broader claim kinds\n- improved parent/child provenance\n- CQ polarity answers treated as decomposable claims, not only as static support/attack placeholders\n\n**Frontend**\n\n- better \"this still bundles multiple claims\" indicators\n- easier drill-down from claim page\n- direct deepening handoffs from critical-question cards into bundled polarity answers\n\n**Testing**\n\n- bundled-claim detection on representative object-level texts\n- preservation of provenance when a claim becomes multiple subclaims\n- no silent breakage of QBAF assumptions when mother claims gain explicit substructure\n\n### Phase 4 Matrix\n\n**Objective**\nShared external-text workbench\n\n**Backend**\n\n- multi-reading / multi-pass text analysis support\n- comparison endpoints\n\n**Frontend**\n\n- text-centered workspace UI\n- compare Deliberus vs human vs revised structure\n\n**Testing**\n\n- asynchronous multi-pass work on the same text\n- stable separation between source-derived structure and later interpretive additions\n- usability on one external text without synchronous coordination\n\n### Phase 5 Matrix\n\n**Objective**\nEpistemic memory\n\n**Backend**\n\n- supersession/version links\n- history queries\n\n**Frontend**\n\n- current formulation plus history drawer\n\n**Testing**\n\n- refinement does not erase prior states\n- current-best view remains simple while history remains inspectable\n\n### Phase 6 Matrix\n\n**Objective**\nClarification-oriented feed\n\n**Backend**\n\n- feed ranking by unresolved concepts / bundle blur / change salience\n- watchlists\n\n**Frontend**\n\n- clearer feed reasons\n- watch modes\n\n**Testing**\n\n- feed reasons are intelligible to a user\n- surfaced items correspond to actual clarification opportunities, not arbitrary salience\n\n### Phase 7 Matrix\n\n**Objective**\nEarned bridging/worldview functionality\n\n**Backend**\n\n- clustering and bridging metrics from real graph data\n\n**Frontend**\n\n- explanation-first bridging views\n- parallax markers\n\n**Testing**\n\n- distinguish at least some semantic disagreements from non-semantic ones\n- detect at least some genuine bridging cases from earned graph structure\n\n### Phase 8 Matrix\n\n**Objective**\nInstitutional modes\n\n**Backend**\n\n- corpus-level synthesis and change tracking\n- organization-facing workflows that preserve provenance\n\n**Frontend**\n\n- corpus workspaces\n- institution-friendly navigation without flattening to dashboards only\n\n**Testing**\n\n- usefulness on a real multi-document corpus\n- no collapse into \"upload files, receive canned report\"\n\n---\n\n## 8. Practical Execution Guidance for the Current Environment\n\nThis plan is being executed on the current MERIAN setup, where local graph infrastructure is not assumed to be available.\n\nThat has two implications:\n\n- code should still be written against the real graph interfaces\n- verification should prefer local-safe, mocked, and structurally narrow tests unless graph infrastructure is explicitly available\n\nThis is not a compromise in standards. It is a sequencing discipline:\n\n- prove route contracts\n- prove model/ontology changes\n- prove frontend/backend integration surfaces\n- avoid pretending to have end-to-end graph verification when the environment does not support it\n\nBroader graph-bound tests should be added or run when the appropriate infrastructure is present, but they should not block shipping clearly correct local slices.\n\n---\n\n## 9. Decision Rule for Every Future Subproject\n\nBefore implementing any new feature or major refactor, ask:\n\n1. Does this help a user say more exactly what they mean?\n2. Does this help the graph represent that clarification or decomposition faithfully?\n3. Does this improve the system's ability to distinguish semantic blur, evidential weakness, structural bundling, and genuine deeper disagreement?\n4. Does this move analysis in service of attunement, or merely produce more impressive structure?\n5. If this were the next shipped thing, would it bring Deliberus closer to being a clarification machine rather than a graph spectacle?\n\nIf the answer is mostly no, the work is probably mistimed.\n\n**Backend**\n\n- corpus workflows\n- summary/export layers\n\n**Frontend**\n\n- corpus navigation\n- institutional overlays\n\n---\n\n## 8. Verification Strategy\n\nEach tranche should be verified at three levels:\n\n1. **Ontology integrity**\n   The graph meaning remains coherent.\n\n2. **Behavioral integrity**\n   A user can actually perform the intended epistemic act.\n\n3. **Philosophical integrity**\n   The new feature reduces confusion or deepens structure rather than merely adding surface complexity.\n\nThis means every major implementation step should be testable with:\n\n- one synthetic unit/integration case\n- one claim-level manual UX trial\n- one real external text where the new behavior is actually useful\n\n---\n\n## 9. What To Explicitly Avoid While Executing\n\n- broad social/community mechanics before clarification works\n- reputation-system elaboration too early\n- heavy worldview taxonomy design\n- overformalized logical machinery that outruns user value\n- graph visuals as a substitute for graph meaning\n- preserving history in ways that make rapid clarification harder\n\n---\n\n## 10. Immediate Next Action\n\nThe immediate next action is:\n\n**Implement Tranche A: the minimum viable clarification primitive.**\n\nThat means:\n\n- expose contested concepts and candidate senses at the claim level\n- let a logged-in user clarify what a term means in a claim\n- store that clarification as a definitional claim in the graph\n- link it structurally to the target claim\n- surface the result back on the claim page\n\nThis is the smallest real step from \"Deliberus extracts argument structure\" to \"Deliberus helps people clarify what they mean.\"\n"}