Skip to Content

Wiki source code of Requirements

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