Skip to Content

Wiki source code of Requirements

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