Changes for page Requirements

Last modified by Robert Schaub on 2025/12/24 20:34

From 3.1 to 2.1 From 8.1 to 7.1

From version 7.1

edited by Robert Schaub
on 2025/12/14 22:27

Change comment: Imported from XAR

To version 3.1

edited by Robert Schaub
on 2025/12/12 15:41

Change comment: Imported from XAR

Raw
Rendered

Summary

Page properties (1 modified, 0 added, 0 removed)

Details

Page properties

Content

@@ -1,289 +1,441 @@
  = Requirements =
--This page defines **Roles**, **Responsibilities**, and **Rules** for contributors and users of FactHarbor.
++This chapter defines all functional, non-functional, user-role, and federation requirements for FactHarbor.
--== Roles ==
++It answers:
--=== Reader ===
++* Who can do what in the system?
++* What workflows must FactHarbor support?
++* What quality, transparency, and federation guarantees must be met?
--**Who**: Anyone (no login required).
++----
--**Can**:
--* Browse and search claims
--* View scenarios, evidence, verdicts, and timelines
--* Compare scenarios and explore assumptions
--* Flag issues, errors, contradictions, or suspicious patterns
--* Use filters, search, and visualization tools
--* Create personal views (saved searches, bookmarks - local browser storage)
--* **Submit claims automatically** by providing text to analyze - new claims are added automatically unless equal claims already exist in the system
++= User Roles =
--**Cannot**:
--* Modify existing content
--* Access draft content
--* Participate in governance decisions
++== Reader ==
--**Note**: Readers can request human review of AI-generated content by flagging it.
++Responsibilities:
--=== Contributor ===
++* Browse and search claims
++* View scenarios, evidence, verdicts, and timelines
++* Compare scenarios and explore assumptions
++* Flag issues, errors, contradictions, or suspicious patterns
--**Who**: Registered and logged-in users (extends Reader capabilities).
++Permissions:
--**Can**:
--* Everything a Reader can do
--* Submit claims
--* Submit evidence
--* Provide feedback
--* Suggest scenarios
--* Flag content for review
--* Request human review of AI-generated content
++* Read-only access to all published claims, scenarios, evidence, and verdicts
++* Use filters, search, and visualization tools (“truth landscape”, timelines, scenario comparison, etc.)
++* Create personal views (saved searches, bookmarks, etc.)
--**Cannot**:
--* Publish or mark content as "reviewed" or "approved"
--* Override expert or maintainer decisions
--* Directly modify AKEL or quality gate configurations
++Limitations:
--=== Reviewer ===
++* Cannot change shared content
++* Cannot publish new claims, scenarios, or verdicts
--**Who**: Trusted community members, appointed by maintainers.
++----
--**Can**:
--* Review contributions from Contributors and AKEL drafts
--* Validate AI-generated content (Mode 2 → Mode 3 transition)
--* Edit claims, scenarios, and evidence
--* Add clarifications or warnings
--* Change content status: `draft` → `in review` → `published` / `rejected`
--* Approve or reject **Tier B and C** content for "Human-Reviewed" status
--* Flag content for expert review
--* Participate in audit sampling
++== Contributor ==
--**Cannot**:
--* Approve Tier A content for "Human-Reviewed" status (requires Expert)
--* Change governance rules
--* Unilaterally change expert conclusions without process
--* Bypass quality gates
++Responsibilities:
--**Note on AI-Drafted Content**:
--* Reviewers can validate AI-generated content (Mode 2) to promote it to "Human-Reviewed" (Mode 3)
--* For Tier B and C, Reviewers have approval authority
--* For Tier A, only Experts can grant "Human-Reviewed" status
++* Submit claims
++* Propose new claim clusters (if automatic clustering is insufficient)
++* Draft scenarios (definitions, assumptions, boundaries)
++* Attach evidence (sources, documents, links, datasets)
++* Suggest verdict drafts and uncertainty ranges
++* Respond to reviewer or expert feedback
--=== Expert (Domain-Specific) ===
++Permissions:
--**Who**: Subject-matter specialists in specific domains (medicine, law, science, etc.).
++* Everything a Reader can do
++* Create and edit **draft** claims, scenarios, evidence links, and verdict drafts
++* Comment on existing content and discuss assumptions
++* Propose corrections to misclassified or outdated content
--**Can**:
--* Everything a Reviewer can do
--* **Final authority** on Tier A content "Human-Reviewed" status
--* Validate complex or controversial claims in their domain
--* Define domain-specific quality standards
--* Set reliability thresholds for domain sources
--* Participate in risk tier assignment review
--* Override AKEL suggestions in their domain (with documentation)
++Limitations:
--**Cannot**:
--* Change platform governance policies
--* Approve content outside their expertise domain
--* Bypass technical quality gates (but can flag for adjustment)
++* Cannot *publish* or mark content as “reviewed” or “approved”
++* Cannot override expert or maintainer decisions
++* Cannot change system-level settings, roles, or federation configuration
--**Specialization**:
--* Experts are domain-specific (e.g., "Medical Expert", "Legal Expert", "Climate Science Expert")
--* Cross-domain claims may require multiple expert reviews
++----
--=== Auditor ===
++== Reviewer ==
--**Who**: Reviewers or Experts assigned to sampling audit duties.
++Responsibilities:
--**Can**:
--* Review sampled AI-generated content against quality standards
--* Validate quality gate enforcement
--* Identify patterns in AI errors or hallucinations
--* Provide feedback for system improvement
--* Flag content for immediate review if errors found
--* Contribute to audit statistics and transparency reports
++* Review contributions from Contributors and AKEL drafts
++* Check internal consistency and clarity of scenarios
++* Validate that evidence is correctly linked and described
++* Ensure verdicts match the evidence and stated assumptions
++* Reject, request change, or accept content
--**Cannot**:
--* Change audit sampling algorithms (maintainer responsibility)
--* Bypass normal review workflows
--* Audit content they personally created
++Permissions:
--**Selection**:
--* Auditors selected based on domain expertise and review quality
--* Rotation to prevent audit fatigue
--* Stratified assignment (Tier A auditors need higher expertise)
++* Everything a Contributor can do
++* Change content status from `draft` → `in review` → `published` / `rejected`
++* Send content back to Contributors with comments
++* Flag content for expert review
--**Audit Focus**:
--* Tier A: Recommendation 30-50% sampling rate, expert auditors
--* Tier B: Recommendation 10-20% sampling rate, reviewer/expert auditors
--* Tier C: Recommendation 5-10% sampling rate, reviewer auditors
++Limitations:
--=== Moderator ===
++* Cannot modify system-wide configuration or federation topology
++* Cannot unilaterally change expert conclusions without process
--**Who**: Maintainers or trusted long-term contributors.
++----
--**Can**:
--* All Reviewer and Expert capabilities (cross-domain)
--* Manage user accounts and permissions
--* Handle disputes and conflicts
--* Enforce community guidelines
--* Suspend or ban abusive users
--* Finalize publication status for sensitive content
--* Review and adjust risk tier assignments
--* Oversee audit system performance
++== Expert ==
--**Cannot**:
--* Change core data model or architecture
--* Override technical system constraints
--* Make unilateral governance decisions without consensus
++Responsibilities:
--=== Maintainer ===
++* Provide domain-specific judgment on scenarios, evidence, and verdicts
++* Refine assumptions and definitions in complex or ambiguous topics
++* Identify subtle biases, missing evidence, or misinterpretations
++* Propose improved verdicts and uncertainty assessments
--**Who**: Core team members responsible for the platform.
++Permissions:
--**Can**:
--* All Moderator capabilities
--* Change data model, architecture, and technical systems
--* Configure quality gates and AKEL parameters
--* Adjust audit sampling algorithms
--* Set and modify risk tier policies
--* Make platform-wide governance decisions
--* Access and modify backend systems
--* Deploy updates and fixes
--* Grant and revoke roles
++* Everything a Reviewer can do
++* Attach expert annotations and signed opinions to scenarios and verdicts
++* Propose re-evaluation of already published content based on new evidence
--**Governance**:
--* Maintainers operate under organizational governance rules
--* Major policy changes require Governing Team approval
--* Technical decisions made collaboratively
++Limitations:
++* Expert status is scoped to specific domains
++* Cannot bypass moderation, abuse policies, or legal constraints
++
  ----
--== Content Publication States ==
++== Moderator ==
--=== Mode 1: Draft ===
--* Not visible to public
--* Visible to contributor and reviewers
--* Can be edited by contributor or reviewers
--* Default state for failed quality gates
++Responsibilities:
--=== Mode 2: AI-Generated (Published) ===
--* **Public** and visible to all users
--* Clearly labeled as "AI-Generated, Awaiting Human Review"
--* Passed all automated quality gates
--* Risk tier displayed (A/B/C)
--* Users can:
--  ** Read and use content
--  ** Request human review
--  ** Flag for expert attention
--* Subject to sampling audits
--* Can be promoted to Mode 3 by reviewer/expert validation
++* Handle abuse reports, spam, harassment, and coordinated manipulation
++* Enforce community guidelines and legal constraints
++* Manage user bans, content takedowns, and visibility restrictions
--=== Mode 3: Human-Reviewed (Published) ===
--* **Public** and visible to all users
--* Labeled as "Human-Reviewed" with reviewer/expert attribution
--* Passed quality gates + human validation
--* Highest trust level
--* For Tier A, requires Expert approval
--* For Tier B/C, Reviewer approval sufficient
++Permissions:
--=== Rejected ===
--* Not visible to public
--* Visible to contributor with rejection reason
--* Can be resubmitted after addressing issues
--* Rejection logged for transparency
++* Hide or temporarily disable access to abusive content
++* Ban or restrict users in line with policy
++* Edit or redact sensitive content (e.g., doxxing, illegal material)
++Limitations:
++
++* Does not change factual verdicts except where required for legal / safety reasons
++* Substantive fact changes must go through the review / expert process
++
  ----
--== Contribution Rules ==
++== Maintainer / Administrator ==
--=== All Contributors Must: ===
--* Provide sources for claims
--* Use clear, neutral language
--* Avoid personal attacks or insults
--* Respect intellectual property (cite sources)
--* Accept community feedback gracefully
++Responsibilities:
--=== AKEL (AI) Must: ===
--* Mark all outputs with `AuthorType = AI`
--* Pass quality gates before Mode 2 publication
--* Perform mandatory contradiction search
--* Disclose confidence levels and uncertainty
--* Provide traceable reasoning chains
--* Flag potential bubbles or echo chambers
--* Submit to audit sampling
++* Maintain node configuration, security settings, and backups
++* Configure AKEL, storage, federation endpoints, and performance tuning
++* Manage role assignments (who is Reviewer, Expert, Moderator, etc.)
++* Approve software updates and schema migrations
--=== Reviewers Must: ===
--* Be impartial and evidence-based
--* Document reasoning for decisions
--* Escalate to experts when appropriate
--* Participate in audits when assigned
--* Provide constructive feedback
++Permissions:
--=== Experts Must: ===
--* Stay within domain expertise
--* Disclose conflicts of interest
--* Document specialized terminology
--* Provide reasoning for domain-specific decisions
--* Participate in Tier A audits
++* All read/write access to configuration, but not necessarily content editorial authority
++* Define organization-level policies (e.g., which sources are allowed by default)
++Limitations:
++
++* Editorial decisions on controversial topics follow governance rules, not arbitrary admin choice
++
  ----
--== Quality Standards ==
++== AKEL (AI Knowledge Extraction Layer) ==
--=== Source Requirements ===
--* Primary sources preferred over secondary
--* Publication date and author must be identifiable
--* Sources must be accessible (not paywalled when possible)
--* Contradictory sources must be acknowledged
--* Echo chamber sources must be flagged
++Responsibilities:
--=== Claim Requirements ===
--* Falsifiable or evaluable
--* Clear definitions of key terms
--* Boundaries and scope stated
--* Assumptions made explicit
--* Uncertainty acknowledged
++* Propose drafts — never final decisions
++* Normalize claims and extract candidate clusters
++* Draft scenarios, evidence candidates, and preliminary verdict suggestions
++* Propose re-evaluation when new evidence appears
--=== Evidence Requirements ===
--* Relevant to the claim and scenario
--* Reliability assessment provided
--* Methodology described (for studies)
--* Limitations noted
--* Conflicting evidence acknowledged
++Permissions:
++* Create and update **machine-generated drafts** and suggestions
++* Never directly publish content without human approval
++
++Limitations:
++
++* AKEL output is always labeled as AI-generated draft
++* Must be reviewable, auditable, and overridable by humans
++
  ----
--== Risk Tier Assignment ==
++= Functional Requirements =
--**Automated (AKEL)**: Initial tier suggested based on domain, keywords, impact
--**Human Validation**: Moderators or Experts can override AKEL suggestions
--**Review**: Risk tiers periodically reviewed based on audit outcomes
++This section defines what the system must **do**.
--**Tier A Indicators**:
--* Medical diagnosis or treatment advice
--* Legal interpretation or advice
--* Election or voting information
--* Safety or security sensitive
--* Major financial decisions
--* Potential for significant harm
++== Claim Intake & Normalization ==
--**Tier B Indicators**:
--* Complex scientific causality
--* Contested policy domains
--* Historical interpretation with political implications
--* Significant economic impact claims
++=== FR1 – Claim Intake ===
--**Tier C Indicators**:
--* Established historical facts
--* Simple definitions
--* Well-documented scientific consensus
--* Basic reference information
++The system must support Claim creation from:
++* Free-text input
++* URLs (web pages, articles, posts)
++* Uploaded documents and transcripts
++* Structured feeds (optional, e.g. from partner platforms)
++
++Accepted sources:
++
++* Text entered by users
++* URLs
++* Uploaded documents
++* Transcripts
++* Automated ingestion (optional federation input)
++* AKEL extraction from multi-claim texts
++
++=== FR2 – Claim Normalization ===
++
++* Convert diverse inputs into short, structured, declarative claims
++* Preserve original phrasing for reference
++* Avoid hidden reinterpretation; differences between original and normalized phrasing must be visible
++
++=== FR3 – Claim Classification ===
++
++* Classify claims by topic, domain, and type (e.g., quantitative, causal, normative)
++* Suggest which node / experts are relevant
++
++=== FR4 – Claim Clustering ===
++
++* Group similar claims into Claim Clusters
++* Allow manual correction of cluster membership
++* Provide explanation why two claims are considered “same cluster”
++
  ----
--== Related Pages ==
++== Scenario System ==
--* [[AKEL (AI Knowledge Extraction Layer)>>FactHarbor.Specification.AI Knowledge Extraction Layer (AKEL).WebHome]]
--* [[Automation>>FactHarbor.Specification.Automation.WebHome]]
--* [[Workflows>>FactHarbor.Specification.Workflows.WebHome]]
--* [[Governance>>FactHarbor.Organisation.Governance]]
++=== FR5 – Scenario Creation ===
++* Contributors, Reviewers, and Experts can create scenarios
++* AKEL can propose draft scenarios
++* Each scenario is tied to exactly one Claim Cluster
++
++=== FR6 – Required Scenario Fields ===
++
++Each scenario includes:
++
++* Definitions (key terms)
++* Assumptions (explicit, testable where possible)
++* Boundaries (time, geography, population, conditions)
++* Scope of evidence considered
++* Intended decision / context (optional)
++
++=== FR7 – Scenario Versioning ===
++
++* Every change to a scenario creates a new version
++* Previous versions remain accessible with timestamps and rationale
++
++=== FR8 – Scenario Comparison ===
++
++* Users can compare scenarios side by side
++* Show differences in assumptions, definitions, and evidence sets
++
++----
++
++== Evidence Management ==
++
++=== FR9 – Evidence Ingestion ===
++
++* Attach external sources (articles, studies, datasets, reports, transcripts) to Scenarios
++* Allow multiple pieces of evidence per Scenario
++
++=== FR10 – Evidence Assessment ===
++
++For each piece of evidence:
++
++* Assign reliability / quality ratings
++* Capture who rated it and why
++* Indicate known limitations, biases, or conflicts of interest
++
++=== FR11 – Evidence Linking ===
++
++* Link one piece of evidence to multiple scenarios if relevant
++* Make dependencies explicit (e.g., “Scenario A uses subset of evidence used in Scenario B”)
++
++----
++
++== Verdicts & Truth Landscape ==
++
++=== FR12 – Scenario Verdicts ===
++
++For each Scenario:
++
++* Provide a **probability- or likelihood-based verdict**
++* Capture uncertainty and reasoning
++* Distinguish between AKEL draft and human-approved verdict
++
++=== FR13 – Truth Landscape ===
++
++* Aggregate all scenario-specific verdicts into a “truth landscape” for a claim
++* Make disagreements visible rather than collapsing them into a single binary result
++
++=== FR14 – Time Evolution ===
++
++* Show how verdicts and evidence evolve over time
++* Allow users to see “as of date X, what did we know?”
++
++----
++
++== Workflow, Moderation & Audit ==
++
++=== FR15 – Workflow States ===
++
++* Draft → In Review → Published / Rejected
++* Separate states for Claims, Scenarios, Evidence, and Verdicts
++
++=== FR16 – Moderation & Abuse Handling ===
++
++* Allow Moderators to hide content or lock edits for abuse or legal reasons
++* Keep internal audit trail even if public view is restricted
++
++=== FR17 – Audit Trail ===
++
++* Every significant action (create, edit, publish, delete/hide) is logged with:
++  * Who did it
++  * When
++  * What changed
++  * Why (short comment, optional but recommended)
++
++----
++
++= Federation Requirements =
++
++FactHarbor is designed to operate as a **federated network of nodes**.
++
++=== FR18 – Node Autonomy ===
++
++* Each node can run independently (local policies, local users, local moderation)
++* Nodes decide which other nodes to federate with
++
++=== FR19 – Data Sharing Modes ===
++
++Nodes must be able to:
++
++* Share claims and summaries only
++* Share selected claims, scenarios, and verdicts
++* Share full underlying evidence metadata where allowed
++* Opt-out of sharing sensitive or restricted content
++
++=== FR20 – Synchronization & Conflict Handling ===
++
++* Changes from remote nodes must be mergeable or explicitly conflict-marked
++* Conflicting verdicts are allowed and visible; not forced into consensus
++
++=== FR21 – Federation Discovery ===
++
++* Discover other nodes and their capabilities (public endpoints, policies)
++* Allow whitelisting / blacklisting of nodes
++
++**Basic federation** (minimum):
++
++* Subscribe to and import selected claims and scenarios from other nodes
++* Keep provenance (which node originated what)
++* Respect remote deletion / redaction notices where required by policy or law
++
++Advanced federation (later versions):
++
++* Cross-node search
++* Federation-wide discovery and reputation signals
++
++----
++
++= Non-Functional Requirements (NFR) =
++
++== NFR1 – Transparency ==
++
++* All assumptions, evidence, and reasoning behind verdicts must be visible
++* AKEL involvement must be clearly labeled
++* Users must be able to inspect the chain of reasoning and versions
++
++== NFR2 – Security ==
++
++* Role-based access control
++* Transport-level security (HTTPS)
++* Secure storage of secrets (API keys, credentials)
++* Audit trails for sensitive actions
++
++== NFR3 – Privacy & Compliance ==
++
++* Configurable data retention policies
++* Ability to redact or pseudonymize personal data when required
++* Compliance hooks for jurisdiction-specific rules (e.g. GDPR-like deletion requests)
++
++== NFR4 – Performance ==
++
++* POC: typical interactions < 2 s
++* Release 1.0: < 300 ms for common read operations after caching
++* Degradation strategies under load (e.g. partial federation results, limited history)
++
++== NFR5 – Scalability ==
++
++* POC: **Fully automated text-to-truth-landscape** pipeline for validation.
++* Beta 0: ~100 external testers on one node
++* Release 1.0: **2000+ concurrent users** on a reasonably provisioned node
++
++Suggested technical targets for Release 1.0:
++
++* Scalable monolith or early microservice architecture
++* Sharded vector database (for semantic search)
++* Optional IPFS or other decentralized storage for large artefacts
++* Horizontal scalability for read capacity
++
++== NFR6 – Interoperability ==
++
++* Open, documented API
++* Modular AKEL that can be swapped or extended
++* Federation protocols that follow open standards where possible
++* Standard model for external integrations (e.g. news platforms, research tools)
++
++== NFR7 – Observability & Operations ==
++
++* Metrics for performance, errors, and queue backlogs
++* Logs for key flows (claim intake, scenario changes, verdict updates, federation sync)
++* Health endpoints for monitoring
++
++== NFR8 – Maintainability ==
++
++* Clear module boundaries (API, core services, AKEL, storage, federation)
++* Backward-compatible schema migration strategy where feasible
++* Configuration via files / environment variables, not hard-coded
++
++== NFR9 – Usability ==
++
++* UI optimized for **exploring complexity**, not hiding it
++* Support for saved views, filters, and user-level preferences
++* Progressive disclosure: casual users see summaries, advanced users can dive deep
++
++----
++
++= Release Levels =
++
++=== Proof of Concept (POC) ===
++
++* **Status:** Fully Automated "Text to Truth Landscape"
++* **Focus:** Validating automated extraction, scenario generation, and verdict computation without human-in-the-loop.
++* **Goal:** Demonstrate model capability on raw text input.
++
++=== Beta 0 ===
++
++* One or few nodes
++* External testers (~100)
++* Expanded workflows and basic moderation
++* Initial federation experiments
++
++=== Release 1.0 ===
++
++* 2000+ concurrent users
++* Scalable monolith or early microservices
++* Sharded vector DB
++* IPFS optional
++* High automation (AKEL assistance)
++* Multi-node federation
++

Changes for page Requirements

Summary

Details

Applications

Navigation

Need help?