Skip to Content

Wiki source code of Requirements

Last modified by Robert Schaub on 2025/12/24 20:34
Show last authors
1 = Requirements =
2
3 This page defines **Roles**, **Responsibilities**, and **Rules** for contributors and users of Test.FactHarborV09.
4
5 == 1. Roles ==
6
7 === 1.1 Reader ===
8
9 **Who**: Anyone (no login required).
10
11 **Can**:
12
13 * Browse and search claims
14 * View scenarios, evidence, verdicts, and timelines
15 * Compare scenarios and explore assumptions
16 * Flag issues, errors, contradictions, or suspicious patterns
17 * Use filters, search, and visualization tools
18 * Create personal views (saved searches, bookmarks - local browser storage)
19 * **Submit claims automatically** by providing text to analyze - new claims are added automatically unless equal claims already exist in the system
20
21 **Cannot**:
22
23 * Modify existing content
24 * Access draft content
25 * Participate in governance decisions
26
27 **Note**: Readers can request human review of AI-generated content by flagging it.
28
29 === 1.2 Contributor ===
30
31 **Who**: Registered and logged-in users (extends Reader capabilities).
32
33 **Can**:
34
35 * Everything a Reader can do
36 * Submit claims
37 * Submit evidence
38 * Provide feedback
39 * Suggest scenarios
40 * Flag content for review
41 * Request human review of AI-generated content
42
43 **Cannot**:
44
45 * Publish or mark content as "reviewed" or "approved"
46 * Override expert or maintainer decisions
47 * Directly modify AKEL or quality gate configurations
48
49 === 1.3 Reviewer ===
50
51 **Who**: Trusted community members, appointed by maintainers.
52
53 **Can**:
54
55 * Review contributions from Contributors and AKEL drafts
56 * Validate AI-generated content (Mode 2 → Mode 3 transition)
57 * Edit claims, scenarios, and evidence
58 * Add clarifications or warnings
59 * Change content status: `draft` → `in review` → `published` / `rejected`
60 * Approve or reject **Tier B and C** content for "Human-Reviewed" status
61 * Flag content for expert review
62 * Participate in audit sampling
63
64 **Cannot**:
65
66 * Approve Tier A content for "Human-Reviewed" status (requires Expert)
67 * Change governance rules
68 * Unilaterally change expert conclusions without process
69 * Bypass quality gates
70
71 **Note on AI-Drafted Content**:
72
73 * Reviewers can validate AI-generated content (Mode 2) to promote it to "Human-Reviewed" (Mode 3)
74 * For Tier B and C, Reviewers have approval authority
75 * For Tier A, only Experts can grant "Human-Reviewed" status
76
77 === 1.4 Expert (Domain-Specific) ===
78
79 **Who**: Subject-matter specialists in specific domains (medicine, law, science, etc.).
80
81 **Can**:
82
83 * Everything a Reviewer can do
84 * **Final authority** on Tier A content "Human-Reviewed" status
85 * Validate complex or controversial claims in their domain
86 * Define domain-specific quality standards
87 * Set reliability thresholds for domain sources
88 * Participate in risk tier assignment review
89 * Override AKEL suggestions in their domain (with documentation)
90
91 **Cannot**:
92
93 * Change platform governance policies
94 * Approve content outside their expertise domain
95 * Bypass technical quality gates (but can flag for adjustment)
96
97 **Specialization**:
98
99 * Experts are domain-specific (e.g., "Medical Expert", "Legal Expert", "Climate Science Expert")
100 * Cross-domain claims may require multiple expert reviews
101
102 === 1.5 Auditor ===
103
104 **Who**: Reviewers or Experts assigned to sampling audit duties.
105
106 **Can**:
107
108 * Review sampled AI-generated content against quality standards
109 * Validate quality gate enforcement
110 * Identify patterns in AI errors or hallucinations
111 * Provide feedback for system improvement
112 * Flag content for immediate review if errors found
113 * Contribute to audit statistics and transparency reports
114
115 **Cannot**:
116
117 * Change audit sampling algorithms (maintainer responsibility)
118 * Bypass normal review workflows
119 * Audit content they personally created
120
121 **Selection**:
122
123 * Auditors selected based on domain expertise and review quality
124 * Rotation to prevent audit fatigue
125 * Stratified assignment (Tier A auditors need higher expertise)
126
127 **Audit Focus**:
128
129 * Tier A: Recommendation 30-50% sampling rate, expert auditors
130 * Tier B: Recommendation 10-20% sampling rate, reviewer/expert auditors
131 * Tier C: Recommendation 5-10% sampling rate, reviewer auditors
132
133 === 1.6 Moderator ===
134
135 **Who**: Maintainers or trusted long-term contributors.
136
137 **Can**:
138
139 * All Reviewer and Expert capabilities (cross-domain)
140 * Manage user accounts and permissions
141 * Handle disputes and conflicts
142 * Enforce community guidelines
143 * Suspend or ban abusive users
144 * Finalize publication status for sensitive content
145 * Review and adjust risk tier assignments
146 * Oversee audit system performance
147
148 **Cannot**:
149
150 * Change core data model or architecture
151 * Override technical system constraints
152 * Make unilateral governance decisions without consensus
153
154 === 1.7 Maintainer ===
155
156 **Who**: Core team members responsible for the platform.
157
158 **Can**:
159
160 * All Moderator capabilities
161 * Change data model, architecture, and technical systems
162 * Configure quality gates and AKEL parameters
163 * Adjust audit sampling algorithms
164 * Set and modify risk tier policies
165 * Make platform-wide governance decisions
166 * Access and modify backend systems
167 * Deploy updates and fixes
168 * Grant and revoke roles
169
170 **Governance**:
171
172 * Maintainers operate under organizational governance rules
173 * Major policy changes require Governing Team approval
174 * Technical decisions made collaboratively
175
176 == 2. Content Publication States ==
177
178 === 2.1 Mode 1: Draft ===
179
180 * Not visible to public
181 * Visible to contributor and reviewers
182 * Can be edited by contributor or reviewers
183 * Default state for failed quality gates
184
185 === 2.2 Mode 2: AI-Generated (Published) ===
186
187 * **Public** and visible to all users
188 * Clearly labeled as "AI-Generated, Awaiting Human Review"
189 * Passed all automated quality gates
190 * Risk tier displayed (A/B/C)
191 * Users can:
192 ** Read and use content
193 ** Request human review
194 ** Flag for expert attention
195 * Subject to sampling audits
196 * Can be promoted to Mode 3 by reviewer/expert validation
197
198 === 2.3 Mode 3: Human-Reviewed (Published) ===
199
200 * **Public** and visible to all users
201 * Labeled as "Human-Reviewed" with reviewer/expert attribution
202 * Passed quality gates + human validation
203 * Highest trust level
204 * For Tier A, requires Expert approval
205 * For Tier B/C, Reviewer approval sufficient
206
207 === 2.4 Rejected ===
208
209 * Not visible to public
210 * Visible to contributor with rejection reason
211 * Can be resubmitted after addressing issues
212 * Rejection logged for transparency
213
214 == 3. Contribution Rules ==
215
216 === 3.1 All Contributors Must: ===
217
218 * Provide sources for claims
219 * Use clear, neutral language
220 * Avoid personal attacks or insults
221 * Respect intellectual property (cite sources)
222 * Accept community feedback gracefully
223
224 === 3.2 AKEL (AI) Must: ===
225
226 * Mark all outputs with `AuthorType = AI`
227 * Pass quality gates before Mode 2 publication
228 * Perform mandatory contradiction search
229 * Disclose confidence levels and uncertainty
230 * Provide traceable reasoning chains
231 * Flag potential bubbles or echo chambers
232 * Submit to audit sampling
233
234 === 3.3 Reviewers Must: ===
235
236 * Be impartial and evidence-based
237 * Document reasoning for decisions
238 * Escalate to experts when appropriate
239 * Participate in audits when assigned
240 * Provide constructive feedback
241
242 === 3.4 Experts Must: ===
243
244 * Stay within domain expertise
245 * Disclose conflicts of interest
246 * Document specialized terminology
247 * Provide reasoning for domain-specific decisions
248 * Participate in Tier A audits
249
250 == 4. Quality Standards ==
251
252 === 4.1 Source Requirements ===
253
254 * Primary sources preferred over secondary
255 * Publication date and author must be identifiable
256 * Sources must be accessible (not paywalled when possible)
257 * Contradictory sources must be acknowledged
258 * Echo chamber sources must be flagged
259
260 === 4.2 Claim Requirements ===
261
262 * Falsifiable or evaluable
263 * Clear definitions of key terms
264 * Boundaries and scope stated
265 * Assumptions made explicit
266 * Uncertainty acknowledged
267
268 === 4.3 Evidence Requirements ===
269
270 * Relevant to the claim and scenario
271 * Reliability assessment provided
272 * Methodology described (for studies)
273 * Limitations noted
274 * Conflicting evidence acknowledged
275
276 == 5. Risk Tier Assignment ==
277
278 **Automated (AKEL)**: Initial tier suggested based on domain, keywords, impact
279 **Human Validation**: Moderators or Experts can override AKEL suggestions
280 **Review**: Risk tiers periodically reviewed based on audit outcomes
281
282 **Tier A Indicators**:
283
284 * Medical diagnosis or treatment advice
285 * Legal interpretation or advice
286 * Election or voting information
287 * Safety or security sensitive
288 * Major financial decisions
289 * Potential for significant harm
290
291 **Tier B Indicators**:
292
293 * Complex scientific causality
294 * Contested policy domains
295 * Historical interpretation with political implications
296 * Significant economic impact claims
297
298 **Tier C Indicators**:
299
300 * Established historical facts
301 * Simple definitions
302 * Well-documented scientific consensus
303 * Basic reference information
304
305
306
307
308 == 6. User Role Hierarchy Diagram ==
309
310 The following diagram visualizes the complete role hierarchy:
311
312 {{include reference="Archive.FactHarbor V0\.9\.23 Lost Data.Specification.Diagrams.User Class Diagram.WebHome"}}
313
314
315
316 == 7. Role Hierarchy Diagrams ==
317
318 === 7.1 User Class Diagram ===
319
320 The following class diagram visualizes the complete user role hierarchy:
321
322 {{include reference="Test.FactHarborV09.Specification.Diagrams.User Class Diagram.WebHome"}}
323
324 === 7.2 Human User Roles ===
325
326 This diagram shows the two-track progression for human users:
327
328 {{include reference="Test.FactHarborV09.Specification.Diagrams.Human User Roles.WebHome"}}
329
330 === 7.3 Technical and System Users ===
331
332 This diagram shows system processes and their management:
333
334 {{include reference="Test.FactHarborV09.Specification.Diagrams.Technical and System Users.WebHome"}}
335
336 **Key Design Principles**:
337 * **Two tracks from Contributor**: Content Track (Reviewer) and Technical Track (Maintainer)
338 * **Technical Users**: System processes (AKEL, bots) managed by Maintainers
339 * **Separation of concerns**: Editorial authority independent from technical authority
340
341
342
343
344
345 = Functional Requirements =
346
347
348
349 This page defines what the FactHarbor system must **do** to fulfill its mission.
350
351 Requirements are structured as FR (Functional Requirement) items and organized by capability area.
352
353
354 == 8. Claim Intake & Normalization ==
355
356 === 8.1 FR1 – Claim Intake ===
357
358 The system must support Claim creation from:
359 * Free-text input (from any Reader)
360 * URLs (web pages, articles, posts)
361 * Uploaded documents and transcripts
362 * Structured feeds (optional, e.g. from partner platforms)
363 * Automated ingestion (federation input)
364 * AKEL extraction from multi-claim texts
365
366 **Automatic submission**: Any Reader can submit text, and new claims are added automatically unless identical claims already exist.
367
368 === 8.2 FR2 – Claim Normalization ===
369
370 * Convert diverse inputs into short, structured, declarative claims
371 * Preserve original phrasing for reference
372 * Avoid hidden reinterpretation; differences between original and normalized phrasing must be visible
373
374 === 8.3 FR3 – Claim Classification ===
375
376 * Classify claims by topic, domain, and type (e.g., quantitative, causal, normative)
377 * Assign risk tier (A/B/C) based on domain and potential impact
378 * Suggest which node / experts are relevant
379
380 === 8.4 FR4 – Claim Clustering ===
381
382 * Group similar claims into Claim Clusters
383 * Allow manual correction of cluster membership
384 * Provide explanation why two claims are considered "same cluster"
385
386
387 == 9. Scenario System ==
388
389 === 9.1 FR5 – Scenario Creation ===
390
391 * Contributors, Reviewers, and Experts can create scenarios
392 * AKEL can propose draft scenarios
393 * Each scenario is tied to exactly one Claim Cluster
394
395 === 9.2 FR6 – Required Scenario Fields ===
396
397 Each scenario includes:
398 * Definitions (key terms)
399 * Assumptions (explicit, testable where possible)
400 * Boundaries (time, geography, population, conditions)
401 * Scope of evidence considered
402 * Intended decision / context (optional)
403
404 === 9.3 FR7 – Scenario Versioning ===
405
406 * Every change to a scenario creates a new version
407 * Previous versions remain accessible with timestamps and rationale
408 * ParentVersionID links versions
409
410 === 9.4 FR8 – Scenario Comparison ===
411
412 * Users can compare scenarios side by side
413 * Show differences in assumptions, definitions, and evidence sets
414
415
416 == 10. Evidence Management ==
417
418 === 10.1 FR9 – Evidence Ingestion ===
419
420 * Attach external sources (articles, studies, datasets, reports, transcripts) to Scenarios
421 * Allow multiple pieces of evidence per Scenario
422 * Support large file uploads (with size limits)
423
424 === 10.2 FR10 – Evidence Assessment ===
425
426 For each piece of evidence:
427 * Assign reliability / quality ratings
428 * Capture who rated it and why
429 * Indicate known limitations, biases, or conflicts of interest
430 * Track evidence version history
431
432 === 10.3 FR11 – Evidence Linking ===
433
434 * Link one piece of evidence to multiple scenarios if relevant
435 * Make dependencies explicit (e.g., "Scenario A uses subset of evidence used in Scenario B")
436 * Use ScenarioEvidenceLink table with RelevanceScore
437
438
439 == 11. Verdicts & Truth Landscape ==
440
441 === 11.1 FR12 – Scenario Verdicts ===
442
443 For each Scenario:
444 * Provide a **probability- or likelihood-based verdict**
445 * Capture uncertainty and reasoning
446 * Distinguish between AKEL draft and human-approved verdict
447 * Support Mode 1 (draft), Mode 2 (AI-generated), Mode 3 (human-reviewed)
448
449 === 11.2 FR13 – Truth Landscape ===
450
451 * Aggregate all scenario-specific verdicts into a "truth landscape" for a claim
452 * Make disagreements visible rather than collapsing them into a single binary result
453 * Show parallel scenarios and their respective verdicts
454
455 === 11.3 FR14 – Time Evolution ===
456
457 * Show how verdicts and evidence evolve over time
458 * Allow users to see "as of date X, what did we know?"
459 * Maintain complete version history for auditing
460
461
462 == 12. Workflow, Moderation & Audit ==
463
464 === 12.1 FR15 – Workflow States ===
465
466 * Draft → In Review → Published / Rejected
467 * Separate states for Claims, Scenarios, Evidence, and Verdicts
468 * Support Mode 1/2/3 publication model
469
470 === 12.2 FR16 – Moderation & Abuse Handling ===
471
472 * Allow Moderators to hide content or lock edits for abuse or legal reasons
473 * Keep internal audit trail even if public view is restricted
474 * Support user reporting and flagging
475
476 === 12.3 FR17 – Audit Trail ===
477
478 * Every significant action (create, edit, publish, delete/hide) is logged with:
479 ** Who did it
480 ** When (timestamp)
481 ** What changed (diffs)
482 ** Why (justification text)
483
484
485 == 13. Quality Gates & AI Review ==
486
487 === 13.1 FR18 – Quality Gate Validation ===
488
489 Before AI-generated content (Mode 2) publication, enforce:
490 * Gate 1: Source Quality
491 * Gate 2: Contradiction Search (MANDATORY)
492 * Gate 3: Uncertainty Quantification
493 * Gate 4: Structural Integrity
494
495 === 13.2 FR19 – Audit Sampling ===
496
497 * Implement stratified sampling by risk tier
498 * Recommendation: 30-50% Tier A, 10-20% Tier B, 5-10% Tier C
499 * Support audit workflow and feedback loop
500
501 === 13.3 FR20 – Risk Tier Assignment ===
502
503 * AKEL suggests tier based on domain, keywords, impact
504 * Moderators and Experts can override
505 * Risk tier affects publication workflow
506
507
508 == 14. Federation Requirements ==
509
510 === 14.1 FR21 – Node Autonomy ===
511
512 * Each node can run independently (local policies, local users, local moderation)
513 * Nodes decide which other nodes to federate with
514 * Trust levels: Trusted / Neutral / Untrusted
515
516 === 14.2 FR22 – Data Sharing Modes ===
517
518 Nodes must be able to:
519 * Share claims and summaries only
520 * Share selected claims, scenarios, and verdicts
521 * Share full underlying evidence metadata where allowed
522 * Opt-out of sharing sensitive or restricted content
523
524 === 14.3 FR23 – Synchronization & Conflict Handling ===
525
526 * Changes from remote nodes must be mergeable or explicitly conflict-marked
527 * Conflicting verdicts are allowed and visible; not forced into consensus
528 * Support push/pull/subscription synchronization
529
530 === 14.4 FR24 – Federation Discovery ===
531
532 * Discover other nodes and their capabilities (public endpoints, policies)
533 * Allow whitelisting / blacklisting of nodes
534 * Global identifier format: `factharbor://node_url/type/local_id`
535
536 === 14.5 FR25 – Cross-Node AI Knowledge Exchange ===
537
538 * Share vector embeddings for clustering
539 * Share canonical claim forms
540 * Share scenario templates
541 * Share contradiction alerts
542 * NEVER share model weights
543 * NEVER override local governance
544
545
546 == 15. Non-Functional Requirements ==
547
548 === 15.1 NFR1 – Transparency ===
549
550 * All assumptions, evidence, and reasoning behind verdicts must be visible
551 * AKEL involvement must be clearly labeled
552 * Users must be able to inspect the chain of reasoning and versions
553
554 === 15.2 NFR2 – Security ===
555
556 * Role-based access control
557 * Transport-level security (HTTPS)
558 * Secure storage of secrets (API keys, credentials)
559 * Audit trails for sensitive actions
560
561 === 15.3 NFR3 – Privacy & Compliance ===
562
563 * Configurable data retention policies
564 * Ability to redact or pseudonymize personal data when required
565 * Compliance hooks for jurisdiction-specific rules (e.g. GDPR-like deletion requests)
566
567 === 15.4 NFR4 – Performance ===
568
569 * POC: typical interactions < 2 s
570 * Release 1.0: < 300 ms for common read operations after caching
571 * Degradation strategies under load
572
573 === 15.5 NFR5 – Scalability ===
574
575 * POC: 50 internal testers on one node
576 * Beta 0: 100 external testers on one node
577 * Release 1.0: **2000+ concurrent users** on a reasonably provisioned node
578
579 Technical targets for Release 1.0:
580 * Scalable monolith or early microservice architecture
581 * Sharded vector database (for semantic search)
582 * Optional IPFS or other decentralized storage for large artifacts
583 * Horizontal scalability for read capacity
584
585 === 15.6 NFR6 – Interoperability ===
586
587 * Open, documented API
588 * Modular AKEL that can be swapped or extended
589 * Federation protocols that follow open standards where possible
590 * Standard model for external integrations
591
592 === 15.7 NFR7 – Observability & Operations ===
593
594 * Metrics for performance, errors, and queue backlogs
595 * Logs for key flows (claim intake, scenario changes, verdict updates, federation sync)
596 * Health endpoints for monitoring
597
598 === 15.8 NFR8 – Maintainability ===
599
600 * Clear module boundaries (API, core services, AKEL, storage, federation)
601 * Backward-compatible schema migration strategy where feasible
602 * Configuration via files / environment variables, not hard-coded
603
604 === 15.9 NFR9 – Usability ===
605
606 * UI optimized for **exploring complexity**, not hiding it
607 * Support for saved views, filters, and user-level preferences
608 * Progressive disclosure: casual users see summaries, advanced users can dive deep
609
610
611 == 16. Release Levels ==
612
613 === 16.1 Proof of Concept (POC) ===
614
615 * Single node
616 * Limited user set (50 internal testers)
617 * Basic claim → scenario → evidence → verdict flow
618 * Minimal federation (optional)
619 * AI-generated publication (Mode 2) demonstration
620 * Quality gates active
621
622 === 16.2 Beta 0 ===
623
624 * One or few nodes
625 * External testers (100)
626 * Expanded workflows and basic moderation
627 * Initial federation experiments
628 * Audit sampling implemented
629
630 === 16.3 Release 1.0 ===
631
632 * 2000+ concurrent users
633 * Scalable architecture
634 * Sharded vector DB
635 * IPFS optional
636 * High automation (AKEL assistance)
637 * Multi-node federation with full sync protocol
638 * Mature audit system
639
640
641
642
643 == 17. Related Pages ==
644
645
646
647 * [[AKEL (AI Knowledge Extraction Layer)>>Test.FactHarborV09.Specification.AI Knowledge Extraction Layer (AKEL).WebHome]]
648 * [[Automation>>Test.FactHarborV09.Specification.Automation.WebHome]]
649 * [[Workflows>>Test.FactHarborV09.Specification.Workflows.WebHome]]
650 * [[Governance>>Test.FactHarborV09.Organisation.Governance]]
651 {{/include}}
652 {{/include}}
653 {{/include}}