Skip to Content

Wiki source code of Requirements

Last modified by Robert Schaub on 2026/02/08 21:23
Show last authors
1 = Requirements =
2
3 This page defines **Roles**, **Responsibilities**, and **Rules** for contributors and users of FactHarbor.
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 == 6. User Role Hierarchy Diagram ==
306
307 The following diagram visualizes the complete role hierarchy:
308
309
310 == 7. Role Hierarchy Diagrams ==
311
312 === 7.1 User Class Diagram ===
313
314 The following class diagram visualizes the complete user role hierarchy:
315
316 {{include reference="Archive.FactHarbor 2026\.01\.20.Specification.Diagrams.User Class Diagram.WebHome"/}}
317
318 === 7.2 Human User Roles ===
319
320 This diagram shows the two-track progression for human users:
321
322 {{include reference="Archive.FactHarbor 2026\.01\.20.Specification.Diagrams.Human User Roles.WebHome"/}}
323
324 === 7.3 Technical and System Users ===
325
326 This diagram shows system processes and their management:
327
328 {{include reference="Archive.FactHarbor 2026\.01\.20.Specification.Diagrams.Technical and System Users.WebHome"/}}
329
330 **Key Design Principles**:
331
332 * **Two tracks from Contributor**: Content Track (Reviewer) and Technical Track (Maintainer)
333 * **Technical Users**: System processes (AKEL, bots) managed by Maintainers
334 * **Separation of concerns**: Editorial authority independent from technical authority
335
336 = Functional Requirements =
337
338
339 This page defines what the FactHarbor system must **do** to fulfill its mission.
340
341 Requirements are structured as FR (Functional Requirement) items and organized by capability area.
342
343
344 == 8. Claim Intake & Normalization ==
345
346 === 8.1 FR1 – Claim Intake ===
347
348 The system must support Claim creation from:
349
350 * Free-text input (from any Reader)
351 * URLs (web pages, articles, posts)
352 * Uploaded documents and transcripts
353 * Structured feeds (optional, e.g. from partner platforms)
354 * Automated ingestion (federation input)
355 * AKEL extraction from multi-claim texts
356
357 **Automatic submission**: Any Reader can submit text, and new claims are added automatically unless identical claims already exist.
358
359 === 8.2 FR2 – Claim Normalization ===
360
361 * Convert diverse inputs into short, structured, declarative claims
362 * Preserve original phrasing for reference
363 * Avoid hidden reinterpretation; differences between original and normalized phrasing must be visible
364
365 === 8.3 FR3 – Claim Classification ===
366
367 * Classify claims by topic, domain, and type (e.g., quantitative, causal, normative)
368 * Assign risk tier (A/B/C) based on domain and potential impact
369 * Suggest which node / experts are relevant
370
371 === 8.4 FR4 – Claim Clustering ===
372
373 * Group similar claims into Claim Clusters
374 * Allow manual correction of cluster membership
375 * Provide explanation why two claims are considered "same cluster"
376
377 == 9. Scenario System ==
378
379 === 9.1 FR5 – Scenario Creation ===
380
381 * Contributors, Reviewers, and Experts can create scenarios
382 * AKEL can propose draft scenarios
383 * Each scenario is tied to exactly one Claim Cluster
384
385 === 9.2 FR6 – Required Scenario Fields ===
386
387 Each scenario includes:
388
389 * Definitions (key terms)
390 * Assumptions (explicit, testable where possible)
391 * Boundaries (time, geography, population, conditions)
392 * Scope of evidence considered
393 * Intended decision / context (optional)
394
395 === 9.3 FR7 – Scenario Versioning ===
396
397 * Every change to a scenario creates a new version
398 * Previous versions remain accessible with timestamps and rationale
399 * ParentVersionID links versions
400
401 === 9.4 FR8 – Scenario Comparison ===
402
403 * Users can compare scenarios side by side
404 * Show differences in assumptions, definitions, and evidence sets
405
406 == 10. Evidence Management ==
407
408 === 10.1 FR9 – Evidence Ingestion ===
409
410 * Attach external sources (articles, studies, datasets, reports, transcripts) to Scenarios
411 * Allow multiple pieces of evidence per Scenario
412 * Support large file uploads (with size limits)
413
414 === 10.2 FR10 – Evidence Assessment ===
415
416 For each piece of evidence:
417
418 * Assign reliability / quality ratings
419 * Capture who rated it and why
420 * Indicate known limitations, biases, or conflicts of interest
421 * Track evidence version history
422
423 === 10.3 FR11 – Evidence Linking ===
424
425 * Link one piece of evidence to multiple scenarios if relevant
426 * Make dependencies explicit (e.g., "Scenario A uses subset of evidence used in Scenario B")
427 * Use ScenarioEvidenceLink table with RelevanceScore
428
429 == 11. Verdicts & Truth Landscape ==
430
431 === 11.1 FR12 – Scenario Verdicts ===
432
433 For each Scenario:
434
435 * Provide a **probability- or likelihood-based verdict**
436 * Capture uncertainty and reasoning
437 * Distinguish between AKEL draft and human-approved verdict
438 * Support Mode 1 (draft), Mode 2 (AI-generated), Mode 3 (human-reviewed)
439
440 === 11.2 FR13 – Truth Landscape ===
441
442 * Aggregate all scenario-specific verdicts into a "truth landscape" for a claim
443 * Make disagreements visible rather than collapsing them into a single binary result
444 * Show parallel scenarios and their respective verdicts
445
446 === 11.3 FR14 – Time Evolution ===
447
448 * Show how verdicts and evidence evolve over time
449 * Allow users to see "as of date X, what did we know?"
450 * Maintain complete version history for auditing
451
452 == 12. Workflow, Moderation & Audit ==
453
454 === 12.1 FR15 – Workflow States ===
455
456 * Draft → In Review → Published / Rejected
457 * Separate states for Claims, Scenarios, Evidence, and Verdicts
458 * Support Mode 1/2/3 publication model
459
460 === 12.2 FR16 – Moderation & Abuse Handling ===
461
462 * Allow Moderators to hide content or lock edits for abuse or legal reasons
463 * Keep internal audit trail even if public view is restricted
464 * Support user reporting and flagging
465
466 === 12.3 FR17 – Audit Trail ===
467
468 * Every significant action (create, edit, publish, delete/hide) is logged with:
469 ** Who did it
470 ** When (timestamp)
471 ** What changed (diffs)
472 ** Why (justification text)
473
474 == 13. Quality Gates & AI Review ==
475
476 === 13.1 FR18 – Quality Gate Validation ===
477
478 Before AI-generated content (Mode 2) publication, enforce:
479
480 * Gate 1: Source Quality
481 * Gate 2: Contradiction Search (MANDATORY)
482 * Gate 3: Uncertainty Quantification
483 * Gate 4: Structural Integrity
484
485 === 13.2 FR19 – Audit Sampling ===
486
487 * Implement stratified sampling by risk tier
488 * Recommendation: 30-50% Tier A, 10-20% Tier B, 5-10% Tier C
489 * Support audit workflow and feedback loop
490
491 === 13.3 FR20 – Risk Tier Assignment ===
492
493 * AKEL suggests tier based on domain, keywords, impact
494 * Moderators and Experts can override
495 * Risk tier affects publication workflow
496
497 == 14. Federation Requirements ==
498
499 === 14.1 FR21 – Node Autonomy ===
500
501 * Each node can run independently (local policies, local users, local moderation)
502 * Nodes decide which other nodes to federate with
503 * Trust levels: Trusted / Neutral / Untrusted
504
505 === 14.2 FR22 – Data Sharing Modes ===
506
507 Nodes must be able to:
508
509 * Share claims and summaries only
510 * Share selected claims, scenarios, and verdicts
511 * Share full underlying evidence metadata where allowed
512 * Opt-out of sharing sensitive or restricted content
513
514 === 14.3 FR23 – Synchronization & Conflict Handling ===
515
516 * Changes from remote nodes must be mergeable or explicitly conflict-marked
517 * Conflicting verdicts are allowed and visible; not forced into consensus
518 * Support push/pull/subscription synchronization
519
520 === 14.4 FR24 – Federation Discovery ===
521
522 * Discover other nodes and their capabilities (public endpoints, policies)
523 * Allow whitelisting / blacklisting of nodes
524 * Global identifier format: `factharbor://node_url/type/local_id`
525
526 === 14.5 FR25 – Cross-Node AI Knowledge Exchange ===
527
528 * Share vector embeddings for clustering
529 * Share canonical claim forms
530 * Share scenario templates
531 * Share contradiction alerts
532 * NEVER share model weights
533 * NEVER override local governance
534
535 == 15. Non-Functional Requirements ==
536
537 === 15.1 NFR1 – Transparency ===
538
539 * All assumptions, evidence, and reasoning behind verdicts must be visible
540 * AKEL involvement must be clearly labeled
541 * Users must be able to inspect the chain of reasoning and versions
542
543 === 15.2 NFR2 – Security ===
544
545 * Role-based access control
546 * Transport-level security (HTTPS)
547 * Secure storage of secrets (API keys, credentials)
548 * Audit trails for sensitive actions
549
550 === 15.3 NFR3 – Privacy & Compliance ===
551
552 * Configurable data retention policies
553 * Ability to redact or pseudonymize personal data when required
554 * Compliance hooks for jurisdiction-specific rules (e.g. GDPR-like deletion requests)
555
556 === 15.4 NFR4 – Performance ===
557
558 * POC: typical interactions < 2 s
559 * Release 1.0: < 300 ms for common read operations after caching
560 * Degradation strategies under load
561
562 === 15.5 NFR5 – Scalability ===
563
564 * POC: 50 internal testers on one node
565 * Beta 0: 100 external testers on one node
566 * Release 1.0: **2000+ concurrent users** on a reasonably provisioned node
567
568 Technical targets for Release 1.0:
569
570 * Scalable monolith or early microservice architecture
571 * Sharded vector database (for semantic search)
572 * Optional IPFS or other decentralized storage for large artifacts
573 * Horizontal scalability for read capacity
574
575 === 15.6 NFR6 – Interoperability ===
576
577 * Open, documented API
578 * Modular AKEL that can be swapped or extended
579 * Federation protocols that follow open standards where possible
580 * Standard model for external integrations
581
582 === 15.7 NFR7 – Observability & Operations ===
583
584 * Metrics for performance, errors, and queue backlogs
585 * Logs for key flows (claim intake, scenario changes, verdict updates, federation sync)
586 * Health endpoints for monitoring
587
588 === 15.8 NFR8 – Maintainability ===
589
590 * Clear module boundaries (API, core services, AKEL, storage, federation)
591 * Backward-compatible schema migration strategy where feasible
592 * Configuration via files / environment variables, not hard-coded
593
594 === 15.9 NFR9 – Usability ===
595
596 * UI optimized for **exploring complexity**, not hiding it
597 * Support for saved views, filters, and user-level preferences
598 * Progressive disclosure: casual users see summaries, advanced users can dive deep
599
600 == 16. Release Levels ==
601
602 === 16.1 Proof of Concept (POC) ===
603
604 * Single node
605 * Limited user set (50 internal testers)
606 * Basic claim → scenario → evidence → verdict flow
607 * Minimal federation (optional)
608 * AI-generated publication (Mode 2) demonstration
609 * Quality gates active
610
611 === 16.2 Beta 0 ===
612
613 * One or few nodes
614 * External testers (100)
615 * Expanded workflows and basic moderation
616 * Initial federation experiments
617 * Audit sampling implemented
618
619 === 16.3 Release 1.0 ===
620
621 * 2000+ concurrent users
622 * Scalable architecture
623 * Sharded vector DB
624 * IPFS optional
625 * High automation (AKEL assistance)
626 * Multi-node federation with full sync protocol
627 * Mature audit system
628
629 == 17. Related Pages ==
630
631
632 * [[AKEL (AI Knowledge Extraction Layer)>>Archive.FactHarbor 2026\.01\.20.Specification.AI Knowledge Extraction Layer (AKEL).WebHome]]
633 * [[Automation>>Archive.FactHarbor 2026\.01\.20.Specification.Automation.WebHome]]
634 * [[Workflows>>Archive.FactHarbor 2026\.01\.20.Specification.Workflows.WebHome]]
635 * [[Governance>>Archive.FactHarbor.Organisation.Governance.WebHome]]