diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index 92702cb..c9763b2 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -1,353 +1,76 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= Changelog - -All notable changes to the Wayfinder project will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) where applicable. - -== Philosophy - -We maintain this changelog with the same values as the project: -- **Transparency**: Document all significant changes -- **Clarity**: Explain the "why" not just the "what" -- **Honesty**: Include mistakes and lessons learned -- **Attribution**: Credit contributors - -== [Unreleased] - -=== Planned -- First example investigation (to be determined based on beta tester feedback) -- Simple website (GitLab Pages or similar) -- Beta tester recruitment (5-10 journalists) -- Level 2A materials (Process Documentarian) -- Level 2B materials (Uncertainty Communicator) - -== [0.2.0-alpha] - 2026-02-07 - -=== Added - Infrastructure & Week 1 Materials - -==== Test Infrastructure -- **Validation test suite**: Framework, documentation, and installation tests -- **validate-framework.sh**: Verifies PROMPT framework, boundary objects, learning pathway integrity -- **validate-documentation.sh**: Checks author attribution, licenses, SPDX headers, consistency -- **validate-installation.sh**: Validates workflows, directory structure, scanning integrations -- **run-all-tests.sh**: Master test runner for full validation -- **Justfile commands**: `test`, `rsr-check`, `verify-scanning`, `validate` - -==== Bot Directives (`.bot_directives/`) -- **8 bot configurations** for gitbot-fleet integration: - - **rhodibot**: RSR compliance and repository operations - - **echidnabot**: Framework consistency verification (PROMPT, boundary objects) - - **glambot**: Documentation quality and WCAG 2.1 AA accessibility - - **sustainabot**: Community health and sustainability monitoring - - **seambot**: Integration and tooling (Hypatia, gitbot-fleet) - - **finishbot**: Milestone tracking and STATE.scm updates - - **robot-repo-automaton**: Automated fixes with confidence thresholds -- **Protection for core frameworks**: All bots configured to preserve PROMPT and heutagogic design - -==== Level 1 Learning Materials (`materials/level-1/`) -- **README.adoc**: Complete Evidence Mapper learning pathway - - 5-step process (4-8 hours total) - - PROMPT framework detailed explanation - - Claim selection criteria (good vs. bad examples) - - Common mistakes and fixes - - Completion checklist - - Pathways to Level 2A/2B -- **PROMPT-Worksheet.adoc**: Evidence evaluation template - - Structured scoring for 6 dimensions (Provenance, Relevance, Objectivity, Methods, Perspective, Timeliness) - - Space for multiple evidence pieces - - Convergence/divergence analysis - - Meta-cognitive reflection prompts - - Epistemic honesty emphasis -- **Evidence-Map-Template.adoc**: Ecosystem mapping guide - - Visual and textual mapping options - - Evidence quality matrix - - Gap identification - - Multi-stakeholder navigation guide (activists, policymakers, skeptics, academics, affected communities) - - Synthesis sections (known/uncertain/unknown) - -==== RSR Compliance Improvements -- **Complete `.machine_readable/` structure**: All 6 SCM files (STATE, META, ECOSYSTEM, AGENTIC, NEUROSYM, PLAYBOOK) -- **Full workflow suite**: 17 workflows (added instant-sync, npm-bun-blocker, ts-blocker, jekyll) -- **License corrections**: Updated all SPDX headers to MPL-2.0 -- **Duplicate cleanup**: Removed .md duplicates (kept .adoc), removed capitalized Justfile - -==== Documentation Updates -- **CITATIONS.adoc**: Corrected author and license (Jonathan D.A. Jewell, MPL-2.0) -- **ROADMAP.adoc**: Updated with actual Wayfinder milestones and 4-week plan -- **STATE.scm**: Project status updated (15% → 30% completion) - -=== Changed - Integration Verification - -==== Hypatia & gitbot-fleet -- **Verified Hypatia scan**: Active on push, PR, weekly schedule -- **Confirmed gitbot-fleet integration**: Automatic finding submission -- **Bot directives active**: All 8 bots configured and ready -- **Neurosymbolic CI/CD**: Intelligence layer operational - -=== Technical Decisions - -==== Why Test Infrastructure First? -- **Rationale**: Documentation projects need validation too -- **Framework integrity**: PROMPT dimensions must remain consistent -- **Formalism checks**: Ensure conceptual coherence -- **Regression prevention**: Changes don't break core frameworks - -==== Why Bot Directives Now? -- **Rationale**: Protect conceptual frameworks from automated changes -- **Learning**: robot-repo-automaton must understand PROMPT is sacred -- **Sustainability**: finishbot tracks milestones, sustainabot monitors health -- **Integration**: seambot ensures Hypatia and gitbot-fleet stay connected - -==== Why Level 1 First? -- **Rationale**: Heutagogic pathway requires self-directed entry point -- **Professional output**: Beta testers need immediate value (4-8 hours) -- **Foundation building**: Level 2A/2B depend on PROMPT framework mastery -- **Test case**: Real journalists will validate design assumptions - -=== Status - -**Current Phase**: Proof-of-concept (Week 1 in progress) - -**Completion**: 30% overall -- ✅ Conceptual frameworks complete -- ✅ Test infrastructure complete -- ✅ Bot directives complete -- ✅ Hypatia/gitbot-fleet verified -- ✅ Level 1 materials complete - -**Week 1 Remaining**: -- Create first example investigation -- Share with 3 journalist friends -- Begin beta tester recruitment - -**Next Milestones**: -- Week 2: Feedback from initial testers -- Week 3: GitLab Pages website -- Week 4: First 5-10 participants start Level 1 - -=== Lessons Learned - -==== What Worked -- **Test-driven documentation**: Validation tests caught outdated licenses, inconsistent attribution -- **Bot directives early**: Protecting frameworks before automation starts prevents future fixes -- **Heutagogic design**: Level 1 materials produce professional output (not just learning badges) -- **Boundary objects**: Evidence map template serves multiple stakeholder needs - -==== What We're Watching -- **Beta tester recruitment**: Will demoralized journalists engage? -- **Level 1 time estimate**: Is 4-8 hours realistic or optimistic? -- **PROMPT scoring**: Will journalists find 0-1 scale intuitive? -- **Evidence mapping**: Hand-drawn vs. tool-based (Obsidian/TiddlyWiki/Notion)? - -=== Contributors - -- Project development: Jonathan D.A. Jewell -- AI assistance: Claude Sonnet 4.5 - -=== Thank You - -To the test infrastructure that caught bugs, the bot directives that will protect frameworks, and the journalists who will test Level 1 materials. - ---- - -== [0.1.0-alpha] - 2025-11-23 - -=== Added - Project Foundation +== Changelog + +All notable changes to `+im-docs+` will be documented in this file. + +This file is generated from conventional commits by the +https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`+changelog-reusable.yml+`] +workflow (`+hyperpolymath/standards#206+`). Adopt the workflow in this +repo’s CI to keep this file in sync automatically — see +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+templates/cliff.toml+`] +for the canonical config. + +The format follows https://keepachangelog.com/en/1.1.0/[Keep a +Changelog]; this project aims to follow +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Added + +* feat(crg): add crg-grade and crg-badge justfile recipes +* feat: add stapeln.toml container definition +* feat: deploy UX Manifesto infrastructure +* feat: add CLADE.a2ml — clade taxonomy declaration +* feat: complete Level 1 Evidence Mapper materials (Week 1) +* feat: add test infrastructure and gitbot-fleet integration +* feat: achieve full RSR compliance for im-docs (Wayfinder) +* feat: add AI Gatekeeper Protocol manifest +* feat(ci): enable Hypatia scanning + +==== Fixed + +* fix(ci): move secret-scanner Cargo.toml gate from job-level if: to st… +(#24) +* fix(ci): bump a2ml/k9-validate-action pins to canonical (#21) +* fix(ci): sync hypatia-scan.yml to canonical (#20) +* fix(ci): adopt canonical hypatia-scan.yml (#19) +* fix(ci): rsr-antipattern.yml duplicate heredoc (#16) +* fix(ci): repair YAML block-scalar in workflow-linter Check Permissions +step (#17) +* fix(scorecard): enforce granular permissions and add fuzzing +placeholder +* fix(ci): Resolve workflow-linter self-matching and metadata issues +* fix: SPDX headers (AGPL→PMPL), email, author name +* fix: correct shell expansion in justfile rsr-check + +==== Changed + +* refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) ==== Documentation -- **README.md**: Project overview, mission, learning pathway, quick start -- **claude.md**: Comprehensive documentation for AI assistants and deep project context -- **LICENSE.txt**: Dual MIT + Palimpsest v0.8 licensing -- **CONTRIBUTING.md**: Contribution guidelines aligned with heutagogic principles -- **CODE_OF_CONDUCT.md**: Community standards emphasizing epistemic virtues -- **SECURITY.md**: Security policy covering source protection, data handling, platform security -- **MAINTAINERS.md**: Governance model and maintainer responsibilities -- **CHANGELOG.md**: This file - -==== Core Frameworks -- **PROMPT Framework**: Six-dimension claim evaluation - - Provenance, Relevance, Objectivity, Methods, Perspective, Timeliness -- **Boundary Objects Theory**: Integration as conceptual foundation - - Enables coordination without consensus - - Multiple entry points for different communities -- **Data → Knowledge → Intelligence → Wisdom Pipeline**: Four-layer architecture -- **Bio-Psycho-Social-Technical Systems Analysis**: Cognitive science integration - -==== Learning Pathway (Heutagogic Design) -- **Level 1**: Skeptical Journalist → Evidence Mapper (4-8 hours) -- **Level 2A**: Methodological Journalist → Process Documentarian (8-12 hours) -- **Level 2B**: Statistical Journalist → Uncertainty Communicator (6-10 hours) -- **Level 3**: Interactive Journalist → Knowledge Architect (20-40 hours) -- **Level 4**: Systems Journalist → Epistemic Infrastructure Builder (ongoing) - -==== Cognitive Science Integration -- Progressive disclosure architecture (avoid cognitive overload) -- Meta-cognitive prompts (make thinking visible) -- Empathy-first contradictory evidence (reduce defensiveness) -- Transparent navigation analytics (show exploration patterns) -- Trust calibration mechanisms - -==== Design Principles -- Face-saving architecture (never "you were wrong") -- Identity-safe framings (Kahan's cultural cognition) -- Multiple entry points (serve different communities) -- Collaborative investigation features -- Accessibility-first (WCAG 2.1 AA minimum) - -=== Context - Why This Project Exists - -This project emerged from recognition that: -1. **We're not in "post-truth"** but in transition from pre-truth to truth -2. **Data is outpacing** knowledge, intelligence, and wisdom -3. **Journalists are demoralized**, seeing "the end of journalism" -4. **Current approaches fail**: Ground News's algorithmic both-sidesism isn't enough -5. **Interactive documentaries** (i-docs) naturally address post-truth pathologies - -=== Influences and Inspiration - -==== Theoretical Foundations -- **Nico Carpentier**: Participatory communication theory, PhD supervision -- **Susan Leigh Star**: Boundary objects theory -- **Ludwig Wittgenstein**: Late work on language games (vs. early truth-value semantics) -- **Dempster-Shafer Theory**: Uncertainty quantification -- **Granger Causality**: Temporal influence without mechanistic causation - -==== Media and Methodology -- **i-Docs Research Network**: Interactive documentary frameworks -- **Korsakow**: Non-linear documentary software (SNUs - smallest narrative units) -- **Notable i-docs**: Out My Window, Hollow, Welcome to Pine Point, Prison Valley - -==== Philosophy and Literature -- **De Man and Derrida**: Irony and the map-territory gap -- **David Foster Wallace**: New Sincerity movement -- **Profilicity vs. Authenticity**: Contemporary debates -- **Oxford OAR Group**: Inventive Methodologies (anecdotes as legitimate knowledge) - -==== Cognitive Science -- **Cowan (2001)**: Working memory limits (~4 chunks) -- **Schwartz**: Choice paralysis -- **Rozenblit & Keil**: Illusion of explanatory depth -- **Kahan**: Cultural cognition and identity-protective reasoning -- **Nickerson**: Understanding disagreement reduces polarization - -==== Professional Practice -- **National Union of Journalists (NUJ)**: Professional journalism standards -- **ProPublica**: Transparent methodology journalism -- **Knight Foundation, Omidyar Network**: Investigative journalism funding models - -=== Technical Decisions - -==== Why Dual Licensing? -- **MIT**: Maximum compatibility, enables wide adoption -- **Palimpsest v0.8**: Values alignment, ensures transparency and epistemic justice -- Both apply; users choose which governs their use - -==== Why This Documentation Structure? -- **README.md**: Quick orientation for humans -- **claude.md**: Deep context for AI assistants -- **Separate guides**: CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, etc. - - Allows targeted reading - - Easier to maintain - - Clearer separation of concerns - -==== Why "Wayfinder"? -- Captures both journalist role (guide) and reader experience (navigator) -- Signals hope to demoralized journalists -- Works as boundary object name (different communities hear what they need) -- Gamification-friendly (Apprentice/Journeyman/Master Wayfinder) -- Memorable, pronounceable, googleable - -=== Lessons Learned - -==== What Worked -- **Delaying specific advice**: Asking questions before prescribing solutions -- **Cognitive science integration**: Design mitigations for known problems -- **Heutagogic approach**: Self-determination + results (not points/badges) -- **Boundary objects framing**: Solves "coordination without consensus" problem - -==== What We're Watching -- **Production cost**: 10x more work than traditional journalism initially -- **Learning curve**: Both journalists and audiences need new capabilities -- **Business model**: No obvious revenue source yet -- **Measurement**: How to prove this works? - -==== Open Questions -- Which complex story for first prototype? -- Obsidian vs. TiddlyWiki vs. Notion for Phase 1? -- How to recruit first 5-10 beta testers? -- What metrics actually matter for "success"? - -=== Status - -**Current Phase**: Conceptual design complete, moving to proof-of-concept - -**Next Milestones**: -1. Week 1: Level 1 materials, evidence mapping template, one example investigation -2. Week 2: Share with 3 journalist friends for feedback -3. Week 3: Build simple website (GitLab Pages) -4. Week 4: First 5-10 participants start Level 1 - -**4 weeks to proof-of-concept.** - -=== Contributors - -- Project inception and design: [Name to be added] -- [Additional contributors as they join] - -=== Thank You - -To everyone who influenced this thinking: -- The demoralized journalists who need hope -- The academics who built the theoretical foundations -- The i-docs practitioners who proved the concept -- The open source community who model transparency -- The cognitive scientists who reveal how we actually think - ---- - -== Versioning Scheme - -=== For Pre-Release (0.x.x) -- **0.x.0**: Major conceptual changes -- **0.0.x**: Documentation updates, minor fixes - -=== For Release (1.x.x and beyond) -- **Major (x.0.0)**: Breaking changes to methodology or platform -- **Minor (0.x.0)**: New features, new levels, significant enhancements -- **Patch (0.0.x)**: Bug fixes, documentation, minor improvements - -=== Special Versions -- **alpha**: Conceptual design, not yet tested -- **beta**: Testing with small group -- **rc**: Release candidate, ready for wider use -- **(no suffix)**: Stable release - ---- - -== How to Use This Changelog -=== For Contributors -- Check Unreleased to see what's coming -- Check your version to know what features are available -- See Attribution to find who to thank or ask +* docs: add TEST-NEEDS.md (CRG C) +* docs: add EXPLAINME.adoc — prove-it file backing README claims +* docs: update CHANGELOG.adoc with v0.2.0-alpha (2026-02-07) +* docs: add checkpoint files for state tracking -=== For Maintainers -- Update Unreleased as you work -- Move to versioned section when releasing -- Always explain why, not just what -- Credit contributors generously +==== CI -=== For Users -- See what's new in each version -- Understand why changes were made -- Know what's planned next -- Track project evolution +* ci: redistribute concurrency-cancel guard to read-only check workflows +(#23) +* ci(secret-scanner): drop duplicate –fail from trufflehog extra_args +(#15) +* ci: bump actions/upload-artifact SHA to current v4 (#14) +* ci: SHA-pin hyperpolymath validate-actions in dogfood-gate +* ci(antipattern): fix top-level dir + benchmark/lsp filename matching +(#13) ---- +=== Pre-history -*This changelog embodies our commitment to transparency. Every significant change is documented with reasoning. Every contributor is credited. Every lesson is shared.* +Prior commits to this file’s introduction are recorded in git history +but not formally classified into Keep-a-Changelog sections. To backfill, +run `+git cliff -o CHANGELOG.md+` locally using the canonical +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+cliff.toml+`] +— this is one-shot mechanical work. -*See also: [README.md](./README.md), [CONTRIBUTING.md](./CONTRIBUTING.md)* +''''' diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index cd33efc..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,70 +0,0 @@ - -# Changelog - -All notable changes to `im-docs` will be documented in this file. - -This file is generated from conventional commits by the -[`changelog-reusable.yml`](https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml) -workflow (`hyperpolymath/standards#206`). Adopt the workflow in this repo's CI to keep this file in sync automatically — see -[`templates/cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) -for the canonical config. - -The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); -this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Added - -- feat(crg): add crg-grade and crg-badge justfile recipes -- feat: add stapeln.toml container definition -- feat: deploy UX Manifesto infrastructure -- feat: add CLADE.a2ml — clade taxonomy declaration -- feat: complete Level 1 Evidence Mapper materials (Week 1) -- feat: add test infrastructure and gitbot-fleet integration -- feat: achieve full RSR compliance for im-docs (Wayfinder) -- feat: add AI Gatekeeper Protocol manifest -- feat(ci): enable Hypatia scanning - -### Fixed - -- fix(ci): move secret-scanner Cargo.toml gate from job-level if: to st… (#24) -- fix(ci): bump a2ml/k9-validate-action pins to canonical (#21) -- fix(ci): sync hypatia-scan.yml to canonical (#20) -- fix(ci): adopt canonical hypatia-scan.yml (#19) -- fix(ci): rsr-antipattern.yml duplicate heredoc (#16) -- fix(ci): repair YAML block-scalar in workflow-linter Check Permissions step (#17) -- fix(scorecard): enforce granular permissions and add fuzzing placeholder -- fix(ci): Resolve workflow-linter self-matching and metadata issues -- fix: SPDX headers (AGPL→PMPL), email, author name -- fix: correct shell expansion in justfile rsr-check - -### Changed - -- refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) - -### Documentation - -- docs: add TEST-NEEDS.md (CRG C) -- docs: add EXPLAINME.adoc — prove-it file backing README claims -- docs: update CHANGELOG.adoc with v0.2.0-alpha (2026-02-07) -- docs: add checkpoint files for state tracking - -### CI - -- ci: redistribute concurrency-cancel guard to read-only check workflows (#23) -- ci(secret-scanner): drop duplicate --fail from trufflehog extra_args (#15) -- ci: bump actions/upload-artifact SHA to current v4 (#14) -- ci: SHA-pin hyperpolymath validate-actions in dogfood-gate -- ci(antipattern): fix top-level dir + benchmark/lsp filename matching (#13) - -## Pre-history - -Prior commits to this file's introduction are recorded in git history but not formally classified into Keep-a-Changelog sections. To backfill, run `git cliff -o CHANGELOG.md` locally using the canonical [`cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) — this is one-shot mechanical work. - ---- - - diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..0f12e21 --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,251 @@ +== Code of Conduct + +=== Our Commitment + +We are committed to creating a community where: - *Truth-seeking* is +valued over being right - *Learning* is celebrated, including learning +from mistakes - *Disagreement* is productive, not destructive - +*Everyone* can participate regardless of background, experience, or +viewpoint - *Epistemic humility* is practiced, not just preached + +This isn’t just a code of conduct—it’s a model of the epistemic culture +we’re trying to build for journalism and public discourse. + +=== Our Standards + +==== Examples of Behavior That Contributes to Positive Community + +===== Epistemic Virtues + +* ✅ Acknowledging uncertainty and limitations in your own knowledge +* ✅ Changing your mind publicly when evidence warrants it +* ✅ Asking genuine questions to understand, not to trap +* ✅ Steel-manning opposing viewpoints before critiquing them +* ✅ Distinguishing between "`I don’t understand this`" and "`This is +wrong`" +* ✅ Celebrating others when they update their beliefs + +===== Communication Virtues + +* ✅ Using clear, accessible language +* ✅ Providing context and sources for claims +* ✅ Showing your reasoning, not just conclusions +* ✅ Respecting others’ cognitive load (structure, summaries, links) +* ✅ Assuming good faith until proven otherwise +* ✅ Using "`I`" statements ("`I found X confusing`" not "`X is +stupid`") + +===== Collaborative Virtues + +* ✅ Welcoming newcomers and helping them orient +* ✅ Sharing credit generously +* ✅ Building on others’ ideas while attributing them +* ✅ Offering constructive criticism +* ✅ Accepting feedback with grace +* ✅ Respecting different contribution styles (code, writing, research, +testing, etc.) + +===== Inclusion Virtues + +* ✅ Using inclusive language +* ✅ Respecting preferred names and pronouns +* ✅ Making space for diverse perspectives +* ✅ Considering how policies affect marginalized groups +* ✅ Providing accessibility (alt text, transcripts, clear language) +* ✅ Recognizing that expertise comes in many forms + +==== Examples of Unacceptable Behavior + +===== Epistemic Violations + +* ❌ Presenting opinions as facts without evidence +* ❌ Ignoring contradictory evidence without explanation +* ❌ Moving goalposts when proven wrong +* ❌ Cherry-picking data to support predetermined conclusions +* ❌ Using credentials to shut down discussion ("`I have a PhD, so…`") +* ❌ Demanding certainty where uncertainty is honest + +===== Communication Violations + +* ❌ Personal attacks, insults, or demeaning language +* ❌ Trolling, intentional derailing, or bad-faith arguing +* ❌ Public or private harassment +* ❌ Doxxing or sharing private information without consent +* ❌ Sexual attention or advances (this is a professional space) +* ❌ Deliberately confusing or obfuscating to "`win`" arguments + +===== Collaborative Violations + +* ❌ Taking credit for others’ work +* ❌ Gatekeeping ("`You’re not a real X because…`") +* ❌ Undermining others’ contributions +* ❌ Refusing to engage with feedback +* ❌ Weaponizing the code of conduct to silence dissent +* ❌ Creating hostile environments for any group + +===== Inclusion Violations + +* ❌ Discriminatory language or behavior based on: +** Age, body size, disability, ethnicity, gender identity/expression +** Experience level, education, socioeconomic status +** Nationality, personal appearance, race, religion +** Sexual identity or orientation +* ❌ Unwelcome sexual attention or imagery +* ❌ Deliberate misgendering or use of rejected names +* ❌ Excluding people based on any protected characteristic + +=== Scope + +This Code of Conduct applies: - In project spaces (GitHub, GitLab, +forums, chat) - At events (conferences, workshops, meetups) - When +representing the project publicly - In one-on-one interactions related +to project work + +It applies to everyone: - Project maintainers - Contributors (regular or +occasional) - Participants (learning, testing, using) - Guests and +visitors + +=== Enforcement + +==== Our Responsibilities + +Project maintainers are responsible for: - Clarifying standards of +acceptable behavior - Taking appropriate and fair corrective action - +Removing, editing, or rejecting contributions that violate this Code - +Banning temporarily or permanently anyone whose behavior is +inappropriate + +==== Reporting + +If you experience or witness unacceptable behavior: + +[arabic] +. *For immediate safety concerns*: Contact local authorities first +. *For code violations*: +* Email: [maintainers email - to be added] +* Include: +** Your contact information +** Names of people involved +** Your account of what happened +** Any supporting documentation (links, screenshots) +** Whether you want this to remain confidential +. *What happens next*: +* We’ll acknowledge receipt within 48 hours +* We’ll investigate (talking to all parties) +* We’ll decide on appropriate response +* We’ll inform you of the outcome +* We’ll protect your privacy + +==== Enforcement Guidelines + +We follow graduated responses based on severity and pattern: + +===== Level 1: Correction + +*Behavior*: Minor violation (unintentional, first time) *Response*: +Private message explaining the issue *Outcome*: Apology and behavior +change expected + +===== Level 2: Warning + +*Behavior*: Moderate violation or repeated minor violations *Response*: +Formal written warning *Outcome*: Clear expectations for future behavior + +===== Level 3: Temporary Ban + +*Behavior*: Serious violation or pattern of problematic behavior +*Response*: Temporary removal from community spaces (1-90 days) +*Outcome*: Conditions for return clearly stated + +===== Level 4: Permanent Ban + +*Behavior*: Severe violation, harassment, or repeated pattern +*Response*: Permanent removal from all project spaces *Outcome*: No path +to return + +==== Appeals + +You may appeal an enforcement decision: - Email maintainers within 14 +days - Explain why you believe the decision was incorrect - Provide any +relevant new information - Maintainers will review and respond within 14 +days + +=== Special Note on Intellectual Disagreement + +*Disagreement is not a violation.* + +We distinguish between: + +✅ *Productive disagreement*: - "`I interpret this evidence differently +because…`" - "`Have you considered this alternative explanation?`" - "`I +don’t find that argument convincing, here’s why…`" + +❌ *Unproductive disagreement*: - "`You’re an idiot if you believe +that`" - "`Anyone who thinks X is morally bankrupt`" - "`I’m not going +to explain why you’re wrong, educate yourself`" + +*We want vigorous intellectual debate.* We don’t want personal attacks +disguised as intellectual critique. + +=== Special Note on Epistemic Justice + +Part of our mission is making knowledge creation more equitable. This +means: + +* *Lived experience is a form of expertise* (though not the only form) +* *Different epistemologies are valid* (academic, journalistic, +community-based, etc.) +* *Power shapes knowledge* (acknowledge whose perspectives are +centered/marginalized) +* *Access should be democratic* (don’t create barriers based on +credentials or payment) + +If someone says "`X policy harms my community,`" don’t demand they +provide peer-reviewed studies. Listen, ask questions, and take seriously +their expertise about their own experience. + +=== Acknowledgments + +This Code of Conduct is adapted from: - +https://www.contributor-covenant.org/[Contributor Covenant v2.1] - +https://www.djangoproject.com/conduct/[Django Code of Conduct] - +https://www.rust-lang.org/policies/code-of-conduct[Rust Code of Conduct] + +With additions specific to epistemic communities. + +=== Updates + +This Code of Conduct will evolve: - Based on community feedback - As we +learn what works - To address new situations + +Version history in CHANGELOG.md. + +Current version: 1.0 Last updated: 2025-11-23 + +=== Questions? + +If you’re unsure whether something violates this Code: - When in doubt, +ask! - Email maintainers for private guidance - Open an issue for public +discussion of edge cases + +We’d rather you ask than worry in silence. + +''''' + +=== Our Promise + +We are building a community that models the epistemic culture we want +for journalism and public discourse: + +* Where changing your mind is strength, not weakness +* Where "`I don’t know`" is an acceptable answer +* Where disagreement leads to understanding, not division +* Where everyone can contribute, regardless of background +* Where truth-seeking matters more than being right + +Thank you for helping us create this space. + +''''' + +_See also: link:./CONTRIBUTING.md[CONTRIBUTING.md], +link:./SECURITY.md[SECURITY.md], link:./MAINTAINERS.md[MAINTAINERS.md]_ diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index f48b61f..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,243 +0,0 @@ - -# Code of Conduct - -## Our Commitment - -We are committed to creating a community where: -- **Truth-seeking** is valued over being right -- **Learning** is celebrated, including learning from mistakes -- **Disagreement** is productive, not destructive -- **Everyone** can participate regardless of background, experience, or viewpoint -- **Epistemic humility** is practiced, not just preached - -This isn't just a code of conduct—it's a model of the epistemic culture we're trying to build for journalism and public discourse. - -## Our Standards - -### Examples of Behavior That Contributes to Positive Community - -#### Epistemic Virtues -- ✅ Acknowledging uncertainty and limitations in your own knowledge -- ✅ Changing your mind publicly when evidence warrants it -- ✅ Asking genuine questions to understand, not to trap -- ✅ Steel-manning opposing viewpoints before critiquing them -- ✅ Distinguishing between "I don't understand this" and "This is wrong" -- ✅ Celebrating others when they update their beliefs - -#### Communication Virtues -- ✅ Using clear, accessible language -- ✅ Providing context and sources for claims -- ✅ Showing your reasoning, not just conclusions -- ✅ Respecting others' cognitive load (structure, summaries, links) -- ✅ Assuming good faith until proven otherwise -- ✅ Using "I" statements ("I found X confusing" not "X is stupid") - -#### Collaborative Virtues -- ✅ Welcoming newcomers and helping them orient -- ✅ Sharing credit generously -- ✅ Building on others' ideas while attributing them -- ✅ Offering constructive criticism -- ✅ Accepting feedback with grace -- ✅ Respecting different contribution styles (code, writing, research, testing, etc.) - -#### Inclusion Virtues -- ✅ Using inclusive language -- ✅ Respecting preferred names and pronouns -- ✅ Making space for diverse perspectives -- ✅ Considering how policies affect marginalized groups -- ✅ Providing accessibility (alt text, transcripts, clear language) -- ✅ Recognizing that expertise comes in many forms - -### Examples of Unacceptable Behavior - -#### Epistemic Violations -- ❌ Presenting opinions as facts without evidence -- ❌ Ignoring contradictory evidence without explanation -- ❌ Moving goalposts when proven wrong -- ❌ Cherry-picking data to support predetermined conclusions -- ❌ Using credentials to shut down discussion ("I have a PhD, so...") -- ❌ Demanding certainty where uncertainty is honest - -#### Communication Violations -- ❌ Personal attacks, insults, or demeaning language -- ❌ Trolling, intentional derailing, or bad-faith arguing -- ❌ Public or private harassment -- ❌ Doxxing or sharing private information without consent -- ❌ Sexual attention or advances (this is a professional space) -- ❌ Deliberately confusing or obfuscating to "win" arguments - -#### Collaborative Violations -- ❌ Taking credit for others' work -- ❌ Gatekeeping ("You're not a real X because...") -- ❌ Undermining others' contributions -- ❌ Refusing to engage with feedback -- ❌ Weaponizing the code of conduct to silence dissent -- ❌ Creating hostile environments for any group - -#### Inclusion Violations -- ❌ Discriminatory language or behavior based on: - - Age, body size, disability, ethnicity, gender identity/expression - - Experience level, education, socioeconomic status - - Nationality, personal appearance, race, religion - - Sexual identity or orientation -- ❌ Unwelcome sexual attention or imagery -- ❌ Deliberate misgendering or use of rejected names -- ❌ Excluding people based on any protected characteristic - -## Scope - -This Code of Conduct applies: -- In project spaces (GitHub, GitLab, forums, chat) -- At events (conferences, workshops, meetups) -- When representing the project publicly -- In one-on-one interactions related to project work - -It applies to everyone: -- Project maintainers -- Contributors (regular or occasional) -- Participants (learning, testing, using) -- Guests and visitors - -## Enforcement - -### Our Responsibilities - -Project maintainers are responsible for: -- Clarifying standards of acceptable behavior -- Taking appropriate and fair corrective action -- Removing, editing, or rejecting contributions that violate this Code -- Banning temporarily or permanently anyone whose behavior is inappropriate - -### Reporting - -If you experience or witness unacceptable behavior: - -1. **For immediate safety concerns**: Contact local authorities first - -2. **For code violations**: - - Email: [maintainers email - to be added] - - Include: - - Your contact information - - Names of people involved - - Your account of what happened - - Any supporting documentation (links, screenshots) - - Whether you want this to remain confidential - -3. **What happens next**: - - We'll acknowledge receipt within 48 hours - - We'll investigate (talking to all parties) - - We'll decide on appropriate response - - We'll inform you of the outcome - - We'll protect your privacy - -### Enforcement Guidelines - -We follow graduated responses based on severity and pattern: - -#### Level 1: Correction -**Behavior**: Minor violation (unintentional, first time) -**Response**: Private message explaining the issue -**Outcome**: Apology and behavior change expected - -#### Level 2: Warning -**Behavior**: Moderate violation or repeated minor violations -**Response**: Formal written warning -**Outcome**: Clear expectations for future behavior - -#### Level 3: Temporary Ban -**Behavior**: Serious violation or pattern of problematic behavior -**Response**: Temporary removal from community spaces (1-90 days) -**Outcome**: Conditions for return clearly stated - -#### Level 4: Permanent Ban -**Behavior**: Severe violation, harassment, or repeated pattern -**Response**: Permanent removal from all project spaces -**Outcome**: No path to return - -### Appeals - -You may appeal an enforcement decision: -- Email maintainers within 14 days -- Explain why you believe the decision was incorrect -- Provide any relevant new information -- Maintainers will review and respond within 14 days - -## Special Note on Intellectual Disagreement - -**Disagreement is not a violation.** - -We distinguish between: - -✅ **Productive disagreement**: -- "I interpret this evidence differently because..." -- "Have you considered this alternative explanation?" -- "I don't find that argument convincing, here's why..." - -❌ **Unproductive disagreement**: -- "You're an idiot if you believe that" -- "Anyone who thinks X is morally bankrupt" -- "I'm not going to explain why you're wrong, educate yourself" - -**We want vigorous intellectual debate.** We don't want personal attacks disguised as intellectual critique. - -## Special Note on Epistemic Justice - -Part of our mission is making knowledge creation more equitable. This means: - -- **Lived experience is a form of expertise** (though not the only form) -- **Different epistemologies are valid** (academic, journalistic, community-based, etc.) -- **Power shapes knowledge** (acknowledge whose perspectives are centered/marginalized) -- **Access should be democratic** (don't create barriers based on credentials or payment) - -If someone says "X policy harms my community," don't demand they provide peer-reviewed studies. Listen, ask questions, and take seriously their expertise about their own experience. - -## Acknowledgments - -This Code of Conduct is adapted from: -- [Contributor Covenant v2.1](https://www.contributor-covenant.org/) -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) - -With additions specific to epistemic communities. - -## Updates - -This Code of Conduct will evolve: -- Based on community feedback -- As we learn what works -- To address new situations - -Version history in CHANGELOG.md. - -Current version: 1.0 -Last updated: 2025-11-23 - -## Questions? - -If you're unsure whether something violates this Code: -- When in doubt, ask! -- Email maintainers for private guidance -- Open an issue for public discussion of edge cases - -We'd rather you ask than worry in silence. - ---- - -## Our Promise - -We are building a community that models the epistemic culture we want for journalism and public discourse: - -- Where changing your mind is strength, not weakness -- Where "I don't know" is an acceptable answer -- Where disagreement leads to understanding, not division -- Where everyone can contribute, regardless of background -- Where truth-seeking matters more than being right - -Thank you for helping us create this space. - ---- - -*See also: [CONTRIBUTING.md](./CONTRIBUTING.md), [SECURITY.md](./SECURITY.md), [MAINTAINERS.md](./MAINTAINERS.md)* diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index e9b1993..858f44f 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -1,21 +1,71 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= Contributing Guide +== Contributing -== Getting Started +Thank you for your interest in contributing! We follow a "`Dual-Track`" +architecture where human-readable documentation lives in the root and +machine-readable policies live in `+.machine_readable/+`. -1. Fork the repository -2. Create a feature branch from `main` -3. Sign off commits (`git commit -s`) -4. Submit a pull request +=== How to Contribute -== Commit Guidelines +We welcome contributions in many forms: -* Conventional commits: `type(scope): description` -* Sign all commits (DCO required) -* Atomic, focused commits +* *Code:* Improving the core stack or extensions +* *Documentation:* Enhancing docs or AI manifests +* *Testing:* Adding property-based tests or formal proofs +* *Bug reports:* Filing clear, reproducible issues -== License +=== Getting Started -Contributions licensed under project license. +[arabic] +. *Read the AI Manifest:* Start with `+0-AI-MANIFEST.a2ml+` (if present) +to understand the repository structure. +. *Environment:* Use `+nix develop+` or `+direnv allow+` to set up your +tools. +. *Task Runner:* Use `+just+` to see available commands +(`+just --list+`). +=== Development Workflow + +==== Branch Naming + +.... +docs/short-description # Documentation +test/what-added # Test additions +feat/short-description # New features +fix/issue-number-description # Bug fixes +refactor/what-changed # Code improvements +security/what-fixed # Security fixes +.... + +==== Commit Messages + +We follow https://www.conventionalcommits.org/[Conventional Commits]: + +.... +(): + +[optional body] + +[optional footer] +.... + +Types: `+feat+`, `+fix+`, `+docs+`, `+test+`, `+refactor+`, `+ci+`, +`+chore+`, `+security+` + +=== Reporting Bugs + +Before reporting: 1. Search existing issues 2. Check if it’s already +fixed in `+main+` + +When reporting, include: - Clear, descriptive title - Environment +details (OS, versions, toolchain) - Steps to reproduce - Expected vs +actual behaviour + +=== Code of Conduct + +All contributors are expected to adhere to our +link:CODE_OF_CONDUCT.md[Code of Conduct]. + +=== License + +By contributing, you agree that your contributions will be licensed +under the same license as the project (see LICENSE). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 5d695b0..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,69 +0,0 @@ - -# Contributing - -Thank you for your interest in contributing! We follow a "Dual-Track" architecture where human-readable documentation lives in the root and machine-readable policies live in `.machine_readable/`. - -## How to Contribute - -We welcome contributions in many forms: - -- **Code:** Improving the core stack or extensions -- **Documentation:** Enhancing docs or AI manifests -- **Testing:** Adding property-based tests or formal proofs -- **Bug reports:** Filing clear, reproducible issues - -## Getting Started - -1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.a2ml` (if present) to understand the repository structure. -2. **Environment:** Use `nix develop` or `direnv allow` to set up your tools. -3. **Task Runner:** Use `just` to see available commands (`just --list`). - -## Development Workflow - -### Branch Naming - -``` -docs/short-description # Documentation -test/what-added # Test additions -feat/short-description # New features -fix/issue-number-description # Bug fixes -refactor/what-changed # Code improvements -security/what-fixed # Security fixes -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): - -``` -(): - -[optional body] - -[optional footer] -``` - -Types: `feat`, `fix`, `docs`, `test`, `refactor`, `ci`, `chore`, `security` - -## Reporting Bugs - -Before reporting: -1. Search existing issues -2. Check if it's already fixed in `main` - -When reporting, include: -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour - -## Code of Conduct - -All contributors are expected to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md). - -## License - -By contributing, you agree that your contributions will be licensed under the same license as the project (see [LICENSE](LICENSE)). diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc new file mode 100644 index 0000000..9b836fb --- /dev/null +++ b/GOVERNANCE.adoc @@ -0,0 +1,60 @@ +== Governance + +=== Overview + +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. + +=== Roles and Responsibilities + +==== Maintainers + +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support + +==== Contributors + +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed + +=== Decision Making + +==== Minor Changes + +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates + +==== Major Changes + +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers + +==== Breaking Changes + +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide + +=== Code of Conduct + +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. + +=== Communication + +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions + +=== Licensing + +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. + +''''' + +_Last updated: 2026-07-18_ diff --git a/GOVERNANCE.md b/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..a326671 --- /dev/null +++ b/README.adoc @@ -0,0 +1,208 @@ +https://opensource.org/licenses/MPL-2.0[image:https://img.shields.io/badge/License-MPL_2.0-blue.svg[License: +MPL-2.0]] + +*Status*: Conceptual Design → Proof of Concept Development + +Wayfinder is a heutagogic capability development pathway and interactive +journalism framework designed to transform journalism from static +truth-claims into navigable knowledge ecosystems. + +== The Problem + +We haven’t moved from "`Truth to Post-Truth`" but from an era where +knowledge systems were simpler to one where they’re overwhelmed by data +velocity. *Data is outpacing knowledge, intelligence, and wisdom.* + +Traditional journalism says: "`Here’s what happened.`" Wayfinder says: +"`Here’s the evidence ecosystem. Navigate it. Understand how we know.`" + +== The Solution + +Wayfinder creates *boundary objects*—interactive investigations that +serve different communities while maintaining evidential coherence: + +* *Activists*: Tool for mobilization +* *Policymakers*: Decision support system +* *Academics*: Research resource +* *Skeptics*: Challenge mechanism +* *Affected Communities*: Validation and voice +* *Journalists*: Living investigation + +All use the SAME evidence but interpret it for their needs. This enables +*coordination without consensus*. + +== Core Framework: PROMPT + +Every claim is evaluated across six dimensions: + +* *P*rovenance: Who said it? What’s their track record? +* *R*elevance: Does this actually address the claim? +* *O*bjectivity: What biases exist? Are they disclosed? +* *M*ethods: How was evidence gathered? Is it sound? +* *P*erspective: What viewpoints are represented? What’s missing? +* *T*imeliness: Is this current? Has it been superseded? + +== Knowledge Pipeline: Data → Knowledge → Intelligence → Wisdom + +Traditional journalism conflates all four. Wayfinder separates and makes +each navigable: + +[arabic] +. *Data Layer*: Raw evidence, fully accessible +. *Knowledge Layer*: Structured claims with PROMPT analysis +. *Intelligence Layer*: Pattern recognition, contradiction +identification +. *Wisdom Layer*: Practical reasoning for decision-making + +== For Demoralized Journalists + +> "`You’re not obsolete. You’re needed more than ever—but as Wayfinders, +not gatekeepers. People need guides who show them HOW to navigate +complexity, not just WHAT to believe.`" + +=== The Learning Pathway + +Self-directed, result-focused capability development: + +* *Level 1* (4-8 hours): Evidence Mapper - Map one claim’s evidence +using PROMPT +* *Level 2A* (8-12 hours): Process Documentarian - Show your methodology +transparently +* *Level 2B* (6-10 hours): Uncertainty Communicator - Replace false +certainty with honest uncertainty +* *Level 3* (20-40 hours): Knowledge Architect - Create full interactive +investigation +* *Level 4* (Ongoing): Epistemic Infrastructure Builder - Build tools, +teach others + +Each level produces *usable professional outputs*, not just learning +badges. + +== Quick Start + +=== For Beta Testers (Journalists) + +[arabic] +. *Read*: [claude.md](./claude.md) for full context +. *Try*: Level 1 Evidence Mapping (4 hours) +* Choose one claim you’re currently reporting +* Apply PROMPT framework to evaluate evidence +* See immediate value in your work +. *Decide*: Continue or not (no pressure) + +=== For Academic Partners + +* *PhD Integration*: This research can be dissertation work +* *Curriculum Development*: Level 1-3 as journalism course modules +* *Research Questions*: Measuring impact on comprehension, trust, +behavior change + +=== For Developers + +* *Phase 1* (NOW): Obsidian/TiddlyWiki/Notion prototypes +* *Phase 2* (3-9 months): SvelteKit + PostgreSQL + graph database custom +platform +* *Phase 3* (9-18 months): Ecosystem building, community tools + +== Theoretical Foundations + +=== Boundary Objects (Susan Leigh Star) + +Objects that maintain coherence across communities while adapting to +local needs, enabling coordination without consensus. + +=== Cognitive Science Integration + +* Progressive disclosure (avoid cognitive overload) +* Meta-cognitive prompts (make thinking visible) +* Empathy-first contradictory evidence (reduce defensiveness) +* Transparent navigation analytics (show exploration patterns) + +=== Bio-Psycho-Social-Technical Systems + +Designed considering biological attention limits, psychological identity +protection, social collective sense-making, and technical accessibility +requirements. + +== Project Status + +=== Completed + +* ✅ Conceptual framework (PROMPT, boundary objects, heutagogic design) +* ✅ Four-level capability pathway design +* ✅ Cognitive science integration +* ✅ SWOT analysis +* ✅ Technical architecture planning + +=== In Progress + +* 🔄 Level 1 materials development +* 🔄 Evidence mapping templates +* 🔄 First example investigation + +=== Next Steps (Week 1-4) + +* Week 1: Document Level 1 pathway, create evidence mapping template, +build one example +* Week 2: Share with 3 journalist friends for feedback +* Week 3: Build simple website (GitLab Pages) +* Week 4: First 5-10 participants start Level 1 + +== Key Documents + +* *[claude.md](./claude.md)*: Comprehensive project documentation for AI +assistants +* *[CONTRIBUTING.md](./CONTRIBUTING.md)*: How to contribute to Wayfinder +* *[CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)*: Community standards +* *[SECURITY.md](./SECURITY.md)*: Security and transparency policies + +== Contact & Collaboration + +*Looking For*: - Beta-testing journalists (especially demoralized ones!) +- Academic partners (journalism schools, media studies) - Funders +(Knight Foundation, Omidyar Network, European Media & Information Fund) +- Developers (SvelteKit, PostgreSQL, D3.js) - i-Docs practitioners - +Cognitive scientists interested in epistemic interfaces + +*Philosophy*: Build in public, open source from day one, collaborative +not competitive. + +== License + +This project is licensed under the Mozilla Public License, v. 2.0. See +the `+LICENSE+` file for details. + +SPDX-License-Identifier: CC-BY-SA-4.0 + +== Acknowledgments + +=== Intellectual Foundations + +* *Nico Carpentier*: Participatory communication theory, PhD supervision +* *Susan Leigh Star*: Boundary objects theory +* *i-Docs Research Network*: Interactive documentary frameworks +* *National Union of Journalists (NUJ)*: Professional journalism +practice insights + +=== Inspiration + +* Interactive documentaries: Out My Window, Hollow, Welcome to Pine +Point, Prison Valley +* Tools: Korsakow (non-linear documentary), Klynt, Obsidian, TiddlyWiki +* Cognitive science: Cowan, Schwartz, Kahan, Nickerson +* Epistemology: Wittgenstein (late work on language games), +Dempster-Shafer theory +* Media theory: De Man, Derrida (irony), David Foster Wallace (New +Sincerity) + +''''' + +*Version*: 0.1.0-alpha *Last Updated*: 2025-11-23 *Status*: Pre-release +conceptual design + +*For AI assistants: See [claude.md](./claude.md) for full context and +implementation details.* + +== Architecture + +See TOPOLOGY for a visual architecture map and completion dashboard. diff --git a/README.md b/README.md deleted file mode 100644 index 9700b70..0000000 --- a/README.md +++ /dev/null @@ -1,261 +0,0 @@ - - -[![License: MPL-2.0](https://img.shields.io/badge/License-MPL_2.0-blue.svg)](https://opensource.org/licenses/MPL-2.0) - -**Status**: Conceptual Design → Proof of Concept Development - -Wayfinder is a heutagogic capability development pathway and interactive -journalism framework designed to transform journalism from static -truth-claims into navigable knowledge ecosystems. - -# The Problem - -We haven’t moved from "Truth to Post-Truth" but from an era where -knowledge systems were simpler to one where they’re overwhelmed by data -velocity. **Data is outpacing knowledge, intelligence, and wisdom.** - -Traditional journalism says: "Here’s what happened." Wayfinder says: -"Here’s the evidence ecosystem. Navigate it. Understand how we know." - -# The Solution - -Wayfinder creates **boundary objects**—interactive investigations that -serve different communities while maintaining evidential coherence: - -- **Activists**: Tool for mobilization - -- **Policymakers**: Decision support system - -- **Academics**: Research resource - -- **Skeptics**: Challenge mechanism - -- **Affected Communities**: Validation and voice - -- **Journalists**: Living investigation - -All use the SAME evidence but interpret it for their needs. This enables -**coordination without consensus**. - -# Core Framework: PROMPT - -Every claim is evaluated across six dimensions: - -- \*P\*rovenance: Who said it? What’s their track record? - -- \*R\*elevance: Does this actually address the claim? - -- \*O\*bjectivity: What biases exist? Are they disclosed? - -- \*M\*ethods: How was evidence gathered? Is it sound? - -- \*P\*erspective: What viewpoints are represented? What’s missing? - -- \*T\*imeliness: Is this current? Has it been superseded? - -# Knowledge Pipeline: Data → Knowledge → Intelligence → Wisdom - -Traditional journalism conflates all four. Wayfinder separates and makes -each navigable: - -1. **Data Layer**: Raw evidence, fully accessible - -2. **Knowledge Layer**: Structured claims with PROMPT analysis - -3. **Intelligence Layer**: Pattern recognition, contradiction - identification - -4. **Wisdom Layer**: Practical reasoning for decision-making - -# For Demoralized Journalists - -\> "You’re not obsolete. You’re needed more than ever—but as Wayfinders, -not gatekeepers. People need guides who show them HOW to navigate -complexity, not just WHAT to believe." - -## The Learning Pathway - -Self-directed, result-focused capability development: - -- **Level 1** (4-8 hours): Evidence Mapper - Map one claim’s evidence - using PROMPT - -- **Level 2A** (8-12 hours): Process Documentarian - Show your - methodology transparently - -- **Level 2B** (6-10 hours): Uncertainty Communicator - Replace false - certainty with honest uncertainty - -- **Level 3** (20-40 hours): Knowledge Architect - Create full - interactive investigation - -- **Level 4** (Ongoing): Epistemic Infrastructure Builder - Build tools, - teach others - -Each level produces **usable professional outputs**, not just learning -badges. - -# Quick Start - -## For Beta Testers (Journalists) - -1. **Read**: \[claude.md\](./claude.md) for full context - -2. **Try**: Level 1 Evidence Mapping (4 hours) - - - Choose one claim you’re currently reporting - - - Apply PROMPT framework to evaluate evidence - - - See immediate value in your work - -3. **Decide**: Continue or not (no pressure) - -## For Academic Partners - -- **PhD Integration**: This research can be dissertation work - -- **Curriculum Development**: Level 1-3 as journalism course modules - -- **Research Questions**: Measuring impact on comprehension, trust, - behavior change - -## For Developers - -- **Phase 1** (NOW): Obsidian/TiddlyWiki/Notion prototypes - -- **Phase 2** (3-9 months): SvelteKit + PostgreSQL + graph database - custom platform - -- **Phase 3** (9-18 months): Ecosystem building, community tools - -# Theoretical Foundations - -## Boundary Objects (Susan Leigh Star) - -Objects that maintain coherence across communities while adapting to -local needs, enabling coordination without consensus. - -## Cognitive Science Integration - -- Progressive disclosure (avoid cognitive overload) - -- Meta-cognitive prompts (make thinking visible) - -- Empathy-first contradictory evidence (reduce defensiveness) - -- Transparent navigation analytics (show exploration patterns) - -## Bio-Psycho-Social-Technical Systems - -Designed considering biological attention limits, psychological identity -protection, social collective sense-making, and technical accessibility -requirements. - -# Project Status - -## Completed - -- ✅ Conceptual framework (PROMPT, boundary objects, heutagogic design) - -- ✅ Four-level capability pathway design - -- ✅ Cognitive science integration - -- ✅ SWOT analysis - -- ✅ Technical architecture planning - -## In Progress - -- 🔄 Level 1 materials development - -- 🔄 Evidence mapping templates - -- 🔄 First example investigation - -## Next Steps (Week 1-4) - -- Week 1: Document Level 1 pathway, create evidence mapping template, - build one example - -- Week 2: Share with 3 journalist friends for feedback - -- Week 3: Build simple website (GitLab Pages) - -- Week 4: First 5-10 participants start Level 1 - -# Key Documents - -- **\[claude.md\](./claude.md)**: Comprehensive project documentation - for AI assistants - -- **\[CONTRIBUTING.md\](./CONTRIBUTING.md)**: How to contribute to - Wayfinder - -- **\[CODE_OF_CONDUCT.md\](./CODE_OF_CONDUCT.md)**: Community standards - -- **\[SECURITY.md\](./SECURITY.md)**: Security and transparency policies - -# Contact & Collaboration - -**Looking For**: - Beta-testing journalists (especially demoralized -ones!) - Academic partners (journalism schools, media studies) - Funders -(Knight Foundation, Omidyar Network, European Media & Information -Fund) - Developers (SvelteKit, PostgreSQL, D3.js) - i-Docs -practitioners - Cognitive scientists interested in epistemic interfaces - -**Philosophy**: Build in public, open source from day one, collaborative -not competitive. - -# License - -This project is licensed under the Mozilla Public License, v. 2.0. See -the `LICENSE` file for details. - -SPDX-License-Identifier: CC-BY-SA-4.0 - -# Acknowledgments - -## Intellectual Foundations - -- **Nico Carpentier**: Participatory communication theory, PhD - supervision - -- **Susan Leigh Star**: Boundary objects theory - -- **i-Docs Research Network**: Interactive documentary frameworks - -- **National Union of Journalists (NUJ)**: Professional journalism - practice insights - -## Inspiration - -- Interactive documentaries: Out My Window, Hollow, Welcome to Pine - Point, Prison Valley - -- Tools: Korsakow (non-linear documentary), Klynt, Obsidian, TiddlyWiki - -- Cognitive science: Cowan, Schwartz, Kahan, Nickerson - -- Epistemology: Wittgenstein (late work on language games), - Dempster-Shafer theory - -- Media theory: De Man, Derrida (irony), David Foster Wallace (New - Sincerity) - ------------------------------------------------------------------------- - -**Version**: 0.1.0-alpha **Last Updated**: 2025-11-23 **Status**: -Pre-release conceptual design - -**For AI assistants: See \[claude.md\](./claude.md) for full context and -implementation details.** - -# Architecture - -See TOPOLOGY for a visual -architecture map and completion dashboard. diff --git a/RSR_COMPLIANCE.adoc b/RSR_COMPLIANCE.adoc new file mode 100644 index 0000000..85137e7 --- /dev/null +++ b/RSR_COMPLIANCE.adoc @@ -0,0 +1,421 @@ +== RSR (Rhodium Standard Repository) Compliance Report + +*Project*: Wayfinder - Epistemic Infrastructure for Journalism +*Version*: 0.1.0-alpha *Assessment Date*: 2025-11-23 *Compliance Level*: +Bronze (adapted for research/design project) + +=== RSR Framework Overview + +The Rhodium Standard Repository (RSR) framework ensures: - Complete +transparency and traceability - Democratic accessibility - Offline-first +functionality (where applicable) - Strong documentation standards - +Clear governance - Security and privacy protection + +=== Compliance Checklist + +==== ✅ Category 1: Documentation (100% Complete) + +[width="99%",cols="35%,21%,26%,18%",options="header",] +|=== +|Requirement |Status |Location |Notes +|README.md |✅ Complete |`+/README.md+` |Comprehensive project overview +with quick start + +|LICENSE.txt |✅ Complete |`+/LICENSE.txt+` |Dual MIT + Palimpsest v0.8 + +|CHANGELOG.md |✅ Complete |`+/CHANGELOG.md+` |Following Keep a +Changelog format + +|CONTRIBUTING.md |✅ Complete |`+/CONTRIBUTING.md+` |Heutagogic +contribution model + +|CODE_OF_CONDUCT.md |✅ Complete |`+/CODE_OF_CONDUCT.md+` |Epistemic +virtue-based conduct + +|SECURITY.md |✅ Complete |`+/SECURITY.md+` |Source protection + data +privacy + +|MAINTAINERS.md |✅ Complete |`+/MAINTAINERS.md+` |Governance model + +|claude.md |✅ Complete |`+/claude.md+` |AI assistant context document +|=== + +*Score*: 8/8 required documents = 100% + +==== ✅ Category 2: Well-Known Directory (100% Complete) + +[width="99%",cols="35%,21%,26%,18%",options="header",] +|=== +|Requirement |Status |Location |Notes +|security.txt |✅ Complete |`+/.well-known/security.txt+` |RFC 9116 +compliant + +|ai.txt |✅ Complete |`+/.well-known/ai.txt+` |AI training policy + +|humans.txt |✅ Complete |`+/.well-known/humans.txt+` |Attribution & +colophon +|=== + +*Score*: 3/3 required files = 100% + +==== ⚠️ Category 3: Code Quality (N/A - Research Project) + +[width="100%",cols="47%,28%,25%",options="header",] +|=== +|Requirement |Status |Notes +|Type Safety |N/A |No code yet; principles established in documentation + +|Memory Safety |N/A |Will apply when platform development begins + +|Zero Dependencies |⚠️ Partial |Documentation has zero dependencies; +future platform will minimize + +|Test Coverage |N/A |Will be implemented in Phase 2 (custom platform) +|=== + +*Score*: Deferred to implementation phase + +*Adaptation Note*: This is currently a research/design project. Code +quality standards will apply when: - Level 1-3 materials include +code/tools - Custom platform development begins (Phase 2) - Open-source +tools are released + +==== ✅ Category 4: Transparency (100% Complete) + +[width="100%",cols="43%,25%,32%",options="header",] +|=== +|Requirement |Status |Evidence +|Complete Methodology Documentation |✅ Complete |PROMPT framework fully +documented in claude.md + +|Decision Rationale |✅ Complete |CHANGELOG.md documents "`why`" for all +decisions + +|Version Control |✅ Complete |Git repository with full history + +|Open Development |✅ Complete |Documentation states "`build in public`" + +|Epistemic Humility |✅ Complete |Integrated throughout (see +CODE_OF_CONDUCT.md) +|=== + +*Score*: 5/5 = 100% + +==== ✅ Category 5: Accessibility (100% Complete) + +[width="100%",cols="43%,25%,32%",options="header",] +|=== +|Requirement |Status |Evidence +|Democratic Accessibility |✅ Complete |Stated as core value in +README.md + +|Plain Language |✅ Complete |Documentation uses clear, accessible +language + +|Multiple Entry Points |✅ Complete |Different levels for different +backgrounds + +|No Paywalls |✅ Complete |Open source, free to use + +|Inclusive Language |✅ Complete |CODE_OF_CONDUCT.md enforces inclusive +language + +|Future: WCAG 2.1 AA |📋 Planned |Specified for Phase 2 platform +development +|=== + +*Score*: 5/5 current requirements = 100% + +==== ✅ Category 6: Governance (100% Complete) + +[width="100%",cols="43%,25%,32%",options="header",] +|=== +|Requirement |Status |Evidence +|Clear Maintainer Structure |✅ Complete |MAINTAINERS.md + +|Decision-Making Process |✅ Complete |Consensus model documented + +|Conflict Resolution |✅ Complete |Graduated response in +CODE_OF_CONDUCT.md + +|Community Guidelines |✅ Complete |CONTRIBUTING.md + CODE_OF_CONDUCT.md + +|Succession Planning |✅ Complete |MAINTAINERS.md addresses this +|=== + +*Score*: 5/5 = 100% + +==== ✅ Category 7: Security & Privacy (100% Complete) + +[width="100%",cols="43%,25%,32%",options="header",] +|=== +|Requirement |Status |Evidence +|Security Policy |✅ Complete |SECURITY.md + +|Source Protection |✅ Complete |Journalist source protection in +SECURITY.md + +|Data Sovereignty |✅ Complete |Users own their data (documented) + +|Privacy by Design |✅ Complete |Minimal data collection principles + +|Vulnerability Disclosure |✅ Complete |security.txt + SECURITY.md + +|Responsible Disclosure |✅ Complete |90-day timeline documented +|=== + +*Score*: 6/6 = 100% + +==== ✅ Category 8: Licensing (100% Complete) + +[width="100%",cols="43%,25%,32%",options="header",] +|=== +|Requirement |Status |Evidence +|Clear License |✅ Complete |Dual MIT + Palimpsest v0.8 + +|Values-Aligned License |✅ Complete |Palimpsest v0.8 ensures epistemic +justice + +|Compatibility License |✅ Complete |MIT ensures wide adoption + +|License in Root |✅ Complete |LICENSE.txt in repository root + +|License Referenced |✅ Complete |README.md references licensing +|=== + +*Score*: 5/5 = 100% + +==== ⚠️ Category 9: Build System (Deferred) + +[cols=",,",options="header",] +|=== +|Requirement |Status |Notes +|Reproducible Builds |📋 Planned |Will implement in Phase 2 +|CI/CD Pipeline |📋 Planned |GitLab CI/CD specified for Phase 2 +|Containerization |📋 Planned |Podman specified (not Docker) +|Automated Testing |📋 Planned |Phase 2 implementation +|=== + +*Score*: Deferred to implementation phase + +*Adaptation Note*: Build systems apply when technical platform exists. +Documentation-only projects don’t require build systems. + +==== ✅ Category 10: Community (100% Complete) + +[width="100%",cols="43%,25%,32%",options="header",] +|=== +|Requirement |Status |Evidence +|Contribution Guidelines |✅ Complete |CONTRIBUTING.md + +|Code of Conduct |✅ Complete |CODE_OF_CONDUCT.md + +|Community Spaces Planned |✅ Complete |Forum/Discord specified in docs + +|Welcoming to Newcomers |✅ Complete |Multiple entry points by skill +level + +|Recognition System |✅ Complete |"`Unlocks`" in learning pathway +|=== + +*Score*: 5/5 = 100% + +==== ✅ Category 11: AI/ML Considerations (100% Complete) + +[width="100%",cols="43%,25%,32%",options="header",] +|=== +|Requirement |Status |Evidence +|AI Training Policy |✅ Complete |ai.txt +|AI Usage Policy |✅ Complete |ai.txt +|AI Ethics |✅ Complete |No disinformation use, values alignment +|Claude.md for Context |✅ Complete |Comprehensive AI assistant guide +|=== + +*Score*: 4/4 = 100% + +=== Overall Compliance Summary + +==== Completed Categories (9/11) + +[arabic] +. ✅ Documentation: 100% +. ✅ Well-Known Directory: 100% +. ✅ Transparency: 100% +. ✅ Accessibility: 100% +. ✅ Governance: 100% +. ✅ Security & Privacy: 100% +. ✅ Licensing: 100% +. ✅ Community: 100% +. ✅ AI/ML Considerations: 100% + +==== Deferred Categories (2/11) + +* ⚠️ Code Quality: Deferred to implementation phase +* ⚠️ Build System: Deferred to implementation phase + +*Current Compliance Level*: *Bronze+ (Adapted)* + +*Rationale*: This is a research/design project, not a software project. +Code quality and build system requirements will apply when technical +implementation begins (Phase 2). + +*For equivalent-stage software projects*: This would be *Gold-level* +compliance for documentation and governance. + +=== Adaptations Made for Research Project + +==== 1. Code Quality → Methodology Quality + +* Instead of type safety: Framework rigor (PROMPT scoring) +* Instead of memory safety: Source protection +* Instead of zero dependencies: Self-contained documentation + +==== 2. Build System → Publication System + +* Instead of CI/CD: Version-controlled markdown +* Instead of containerization: Portable document formats +* Instead of automated tests: Peer review processes + +==== 3. Test Coverage → Research Validation + +* User testing with journalists (planned Week 1-4) +* Cognitive science evaluation (planned Phase 1) +* Impact measurement (comprehension, trust, behavior change) + +=== Strengths of Current Implementation + +==== 1. Exemplary Documentation + +* 8 comprehensive documents covering all aspects +* Clear, accessible language +* Transparency about uncertainties and limitations +* Attribution of influences and inspirations + +==== 2. Strong Governance Model + +* Clear decision-making processes +* Epistemic humility embedded in conduct code +* Distributed maintainership +* Succession planning + +==== 3. Values-Aligned Security + +* Source protection as highest priority +* Data sovereignty +* Privacy by design +* Transparency about data handling + +==== 4. Innovative Community Model + +* Heutagogic (self-determined learning) +* Results-focused (not badge-focused) +* Multiple entry points +* Recognition of diverse expertise + +==== 5. Thoughtful AI Policy + +* Allowed with conditions +* Values-aligned restrictions +* Transparency requirements +* Research collaboration welcome + +=== Areas for Future Development + +==== Phase 1 (Weeks 1-4) - Proof of Concept + +* [ ] Level 1 materials (evidence mapping templates) +* [ ] PROMPT scoring worksheets +* [ ] First example investigation +* [ ] Simple website (GitLab Pages) +* [ ] Beta tester recruitment (5-10 journalists) + +==== Phase 2 (Months 3-9) - Custom Platform + +* [ ] Implement code quality standards (type safety, testing) +* [ ] Build CI/CD pipeline (GitLab) +* [ ] Containerization (Podman) +* [ ] WCAG 2.1 AA compliance verification +* [ ] Performance benchmarking + +==== Phase 3 (Months 9-18) - Ecosystem + +* [ ] Modular tool releases (PROMPT scorer, etc.) +* [ ] API development +* [ ] Integration testing +* [ ] Community tool contributions +* [ ] Academic research partnerships + +=== Compliance Verification + +==== How This Assessment Was Conducted + +[arabic] +. Reviewed all documentation against RSR checklist +. Adapted criteria for research vs. software project +. Verified file existence and content quality +. Assessed alignment with RSR values +. Identified deferred vs. not-applicable requirements + +==== Independent Verification + +This assessment can be independently verified by: 1. Checking file +existence: All required files present 2. Reading content: Comprehensive +and values-aligned 3. Comparing to RSR standard: Meets or exceeds +expectations 4. Community feedback: Open to external assessment + +==== Next Assessment + +* *Date*: 2026-05-23 (6 months) +* *Trigger*: Before Phase 2 platform development begins +* *Focus*: Code quality and build system implementation + +=== Recommendations + +==== For Maintainers + +[arabic] +. ✅ *Current state is excellent* - Documentation and governance +exemplary +. 📋 *Maintain this standard* - Don’t let documentation drift +. 📋 *Update regularly* - Keep CHANGELOG.md current as project evolves +. 📋 *Seek community feedback* - Governance model should evolve with +needs + +==== For Contributors + +[arabic] +. Read README.md first for orientation +. Check CONTRIBUTING.md for guidelines +. Review CODE_OF_CONDUCT.md for community standards +. Use claude.md for deep project context + +==== For Users/Adopters + +[arabic] +. This project follows high transparency standards +. Governance is clearly documented and open to community input +. Values (epistemic justice, accessibility) are embedded, not add-ons +. You can trust this project to maintain these standards + +=== Conclusion + +Wayfinder demonstrates *exemplary RSR compliance* for a research/design +project. The documentation is comprehensive, transparent, and +values-aligned. The governance model is clear and democratic. Security +and privacy are appropriately prioritized. + +When technical implementation begins (Phase 2), the project has a solid +foundation for implementing code quality and build system requirements +to achieve *full Gold or Platinum level* RSR compliance. + +*Recommendation*: Approved for Bronze+ compliance with commendation for +documentation excellence. + +''''' + +*Assessed by*: RSR Compliance Review *Date*: 2025-11-23 *Next Review*: +2026-05-23 or before Phase 2 development + +_See also: link:./README.md[README.md], +link:./CONTRIBUTING.md[CONTRIBUTING.md], +link:./CHANGELOG.md[CHANGELOG.md]_ diff --git a/RSR_COMPLIANCE.md b/RSR_COMPLIANCE.md deleted file mode 100644 index 187f15a..0000000 --- a/RSR_COMPLIANCE.md +++ /dev/null @@ -1,313 +0,0 @@ - -# RSR (Rhodium Standard Repository) Compliance Report - -**Project**: Wayfinder - Epistemic Infrastructure for Journalism -**Version**: 0.1.0-alpha -**Assessment Date**: 2025-11-23 -**Compliance Level**: Bronze (adapted for research/design project) - -## RSR Framework Overview - -The Rhodium Standard Repository (RSR) framework ensures: -- Complete transparency and traceability -- Democratic accessibility -- Offline-first functionality (where applicable) -- Strong documentation standards -- Clear governance -- Security and privacy protection - -## Compliance Checklist - -### ✅ Category 1: Documentation (100% Complete) - -| Requirement | Status | Location | Notes | -|-------------|--------|----------|-------| -| README.md | ✅ Complete | `/README.md` | Comprehensive project overview with quick start | -| LICENSE.txt | ✅ Complete | `/LICENSE.txt` | Dual MIT + Palimpsest v0.8 | -| CHANGELOG.md | ✅ Complete | `/CHANGELOG.md` | Following Keep a Changelog format | -| CONTRIBUTING.md | ✅ Complete | `/CONTRIBUTING.md` | Heutagogic contribution model | -| CODE_OF_CONDUCT.md | ✅ Complete | `/CODE_OF_CONDUCT.md` | Epistemic virtue-based conduct | -| SECURITY.md | ✅ Complete | `/SECURITY.md` | Source protection + data privacy | -| MAINTAINERS.md | ✅ Complete | `/MAINTAINERS.md` | Governance model | -| claude.md | ✅ Complete | `/claude.md` | AI assistant context document | - -**Score**: 8/8 required documents = 100% - -### ✅ Category 2: Well-Known Directory (100% Complete) - -| Requirement | Status | Location | Notes | -|-------------|--------|----------|-------| -| security.txt | ✅ Complete | `/.well-known/security.txt` | RFC 9116 compliant | -| ai.txt | ✅ Complete | `/.well-known/ai.txt` | AI training policy | -| humans.txt | ✅ Complete | `/.well-known/humans.txt` | Attribution & colophon | - -**Score**: 3/3 required files = 100% - -### ⚠️ Category 3: Code Quality (N/A - Research Project) - -| Requirement | Status | Notes | -|-------------|--------|-------| -| Type Safety | N/A | No code yet; principles established in documentation | -| Memory Safety | N/A | Will apply when platform development begins | -| Zero Dependencies | ⚠️ Partial | Documentation has zero dependencies; future platform will minimize | -| Test Coverage | N/A | Will be implemented in Phase 2 (custom platform) | - -**Score**: Deferred to implementation phase - -**Adaptation Note**: This is currently a research/design project. Code quality standards will apply when: -- Level 1-3 materials include code/tools -- Custom platform development begins (Phase 2) -- Open-source tools are released - -### ✅ Category 4: Transparency (100% Complete) - -| Requirement | Status | Evidence | -|-------------|--------|----------| -| Complete Methodology Documentation | ✅ Complete | PROMPT framework fully documented in claude.md | -| Decision Rationale | ✅ Complete | CHANGELOG.md documents "why" for all decisions | -| Version Control | ✅ Complete | Git repository with full history | -| Open Development | ✅ Complete | Documentation states "build in public" | -| Epistemic Humility | ✅ Complete | Integrated throughout (see CODE_OF_CONDUCT.md) | - -**Score**: 5/5 = 100% - -### ✅ Category 5: Accessibility (100% Complete) - -| Requirement | Status | Evidence | -|-------------|--------|----------| -| Democratic Accessibility | ✅ Complete | Stated as core value in README.md | -| Plain Language | ✅ Complete | Documentation uses clear, accessible language | -| Multiple Entry Points | ✅ Complete | Different levels for different backgrounds | -| No Paywalls | ✅ Complete | Open source, free to use | -| Inclusive Language | ✅ Complete | CODE_OF_CONDUCT.md enforces inclusive language | -| Future: WCAG 2.1 AA | 📋 Planned | Specified for Phase 2 platform development | - -**Score**: 5/5 current requirements = 100% - -### ✅ Category 6: Governance (100% Complete) - -| Requirement | Status | Evidence | -|-------------|--------|----------| -| Clear Maintainer Structure | ✅ Complete | MAINTAINERS.md | -| Decision-Making Process | ✅ Complete | Consensus model documented | -| Conflict Resolution | ✅ Complete | Graduated response in CODE_OF_CONDUCT.md | -| Community Guidelines | ✅ Complete | CONTRIBUTING.md + CODE_OF_CONDUCT.md | -| Succession Planning | ✅ Complete | MAINTAINERS.md addresses this | - -**Score**: 5/5 = 100% - -### ✅ Category 7: Security & Privacy (100% Complete) - -| Requirement | Status | Evidence | -|-------------|--------|----------| -| Security Policy | ✅ Complete | SECURITY.md | -| Source Protection | ✅ Complete | Journalist source protection in SECURITY.md | -| Data Sovereignty | ✅ Complete | Users own their data (documented) | -| Privacy by Design | ✅ Complete | Minimal data collection principles | -| Vulnerability Disclosure | ✅ Complete | security.txt + SECURITY.md | -| Responsible Disclosure | ✅ Complete | 90-day timeline documented | - -**Score**: 6/6 = 100% - -### ✅ Category 8: Licensing (100% Complete) - -| Requirement | Status | Evidence | -|-------------|--------|----------| -| Clear License | ✅ Complete | Dual MIT + Palimpsest v0.8 | -| Values-Aligned License | ✅ Complete | Palimpsest v0.8 ensures epistemic justice | -| Compatibility License | ✅ Complete | MIT ensures wide adoption | -| License in Root | ✅ Complete | LICENSE.txt in repository root | -| License Referenced | ✅ Complete | README.md references licensing | - -**Score**: 5/5 = 100% - -### ⚠️ Category 9: Build System (Deferred) - -| Requirement | Status | Notes | -|-------------|--------|-------| -| Reproducible Builds | 📋 Planned | Will implement in Phase 2 | -| CI/CD Pipeline | 📋 Planned | GitLab CI/CD specified for Phase 2 | -| Containerization | 📋 Planned | Podman specified (not Docker) | -| Automated Testing | 📋 Planned | Phase 2 implementation | - -**Score**: Deferred to implementation phase - -**Adaptation Note**: Build systems apply when technical platform exists. Documentation-only projects don't require build systems. - -### ✅ Category 10: Community (100% Complete) - -| Requirement | Status | Evidence | -|-------------|--------|----------| -| Contribution Guidelines | ✅ Complete | CONTRIBUTING.md | -| Code of Conduct | ✅ Complete | CODE_OF_CONDUCT.md | -| Community Spaces Planned | ✅ Complete | Forum/Discord specified in docs | -| Welcoming to Newcomers | ✅ Complete | Multiple entry points by skill level | -| Recognition System | ✅ Complete | "Unlocks" in learning pathway | - -**Score**: 5/5 = 100% - -### ✅ Category 11: AI/ML Considerations (100% Complete) - -| Requirement | Status | Evidence | -|-------------|--------|----------| -| AI Training Policy | ✅ Complete | ai.txt | -| AI Usage Policy | ✅ Complete | ai.txt | -| AI Ethics | ✅ Complete | No disinformation use, values alignment | -| Claude.md for Context | ✅ Complete | Comprehensive AI assistant guide | - -**Score**: 4/4 = 100% - -## Overall Compliance Summary - -### Completed Categories (9/11) -1. ✅ Documentation: 100% -2. ✅ Well-Known Directory: 100% -3. ✅ Transparency: 100% -4. ✅ Accessibility: 100% -5. ✅ Governance: 100% -6. ✅ Security & Privacy: 100% -7. ✅ Licensing: 100% -8. ✅ Community: 100% -9. ✅ AI/ML Considerations: 100% - -### Deferred Categories (2/11) -- ⚠️ Code Quality: Deferred to implementation phase -- ⚠️ Build System: Deferred to implementation phase - -**Current Compliance Level**: **Bronze+ (Adapted)** - -**Rationale**: This is a research/design project, not a software project. Code quality and build system requirements will apply when technical implementation begins (Phase 2). - -**For equivalent-stage software projects**: This would be **Gold-level** compliance for documentation and governance. - -## Adaptations Made for Research Project - -### 1. Code Quality → Methodology Quality -- Instead of type safety: Framework rigor (PROMPT scoring) -- Instead of memory safety: Source protection -- Instead of zero dependencies: Self-contained documentation - -### 2. Build System → Publication System -- Instead of CI/CD: Version-controlled markdown -- Instead of containerization: Portable document formats -- Instead of automated tests: Peer review processes - -### 3. Test Coverage → Research Validation -- User testing with journalists (planned Week 1-4) -- Cognitive science evaluation (planned Phase 1) -- Impact measurement (comprehension, trust, behavior change) - -## Strengths of Current Implementation - -### 1. Exemplary Documentation -- 8 comprehensive documents covering all aspects -- Clear, accessible language -- Transparency about uncertainties and limitations -- Attribution of influences and inspirations - -### 2. Strong Governance Model -- Clear decision-making processes -- Epistemic humility embedded in conduct code -- Distributed maintainership -- Succession planning - -### 3. Values-Aligned Security -- Source protection as highest priority -- Data sovereignty -- Privacy by design -- Transparency about data handling - -### 4. Innovative Community Model -- Heutagogic (self-determined learning) -- Results-focused (not badge-focused) -- Multiple entry points -- Recognition of diverse expertise - -### 5. Thoughtful AI Policy -- Allowed with conditions -- Values-aligned restrictions -- Transparency requirements -- Research collaboration welcome - -## Areas for Future Development - -### Phase 1 (Weeks 1-4) - Proof of Concept -- [ ] Level 1 materials (evidence mapping templates) -- [ ] PROMPT scoring worksheets -- [ ] First example investigation -- [ ] Simple website (GitLab Pages) -- [ ] Beta tester recruitment (5-10 journalists) - -### Phase 2 (Months 3-9) - Custom Platform -- [ ] Implement code quality standards (type safety, testing) -- [ ] Build CI/CD pipeline (GitLab) -- [ ] Containerization (Podman) -- [ ] WCAG 2.1 AA compliance verification -- [ ] Performance benchmarking - -### Phase 3 (Months 9-18) - Ecosystem -- [ ] Modular tool releases (PROMPT scorer, etc.) -- [ ] API development -- [ ] Integration testing -- [ ] Community tool contributions -- [ ] Academic research partnerships - -## Compliance Verification - -### How This Assessment Was Conducted -1. Reviewed all documentation against RSR checklist -2. Adapted criteria for research vs. software project -3. Verified file existence and content quality -4. Assessed alignment with RSR values -5. Identified deferred vs. not-applicable requirements - -### Independent Verification -This assessment can be independently verified by: -1. Checking file existence: All required files present -2. Reading content: Comprehensive and values-aligned -3. Comparing to RSR standard: Meets or exceeds expectations -4. Community feedback: Open to external assessment - -### Next Assessment -- **Date**: 2026-05-23 (6 months) -- **Trigger**: Before Phase 2 platform development begins -- **Focus**: Code quality and build system implementation - -## Recommendations - -### For Maintainers -1. ✅ **Current state is excellent** - Documentation and governance exemplary -2. 📋 **Maintain this standard** - Don't let documentation drift -3. 📋 **Update regularly** - Keep CHANGELOG.md current as project evolves -4. 📋 **Seek community feedback** - Governance model should evolve with needs - -### For Contributors -1. Read README.md first for orientation -2. Check CONTRIBUTING.md for guidelines -3. Review CODE_OF_CONDUCT.md for community standards -4. Use claude.md for deep project context - -### For Users/Adopters -1. This project follows high transparency standards -2. Governance is clearly documented and open to community input -3. Values (epistemic justice, accessibility) are embedded, not add-ons -4. You can trust this project to maintain these standards - -## Conclusion - -Wayfinder demonstrates **exemplary RSR compliance** for a research/design project. The documentation is comprehensive, transparent, and values-aligned. The governance model is clear and democratic. Security and privacy are appropriately prioritized. - -When technical implementation begins (Phase 2), the project has a solid foundation for implementing code quality and build system requirements to achieve **full Gold or Platinum level** RSR compliance. - -**Recommendation**: Approved for Bronze+ compliance with commendation for documentation excellence. - ---- - -**Assessed by**: RSR Compliance Review -**Date**: 2025-11-23 -**Next Review**: 2026-05-23 or before Phase 2 development - -*See also: [README.md](./README.md), [CONTRIBUTING.md](./CONTRIBUTING.md), [CHANGELOG.md](./CHANGELOG.md)* diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..4e9620b --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,268 @@ +== Security Policy + +=== Our Approach to Security + +Wayfinder is designed around transparency, democratic accessibility, and +epistemic justice. Our security model reflects these values: + +* *Transparency by default*: Make processes visible, not hidden +* *Distributed verification*: Multiple independent sources of truth +* *Privacy protection*: Respect dignity of sources and participants +* *Data sovereignty*: Users own their contributions + +=== Scope + +This security policy covers: - Research methodology and data handling - +Source protection and attribution - User privacy and data ownership - +Platform security (when technical platform exists) - Community safety +(see CODE_OF_CONDUCT.md) + +=== What We Consider Security Issues + +==== High Severity + +* *Source endangerment*: Exposing confidential sources or whistleblowers +* *Data breaches*: Unauthorized access to user data, investigations, or +evidence +* *Evidence tampering*: Unauthorized modification of source materials +* *Doxing*: Publishing private information without consent +* *Platform vulnerabilities*: Security flaws that could compromise data + +==== Medium Severity + +* *Privacy violations*: Unintentional exposure of personal information +* *Attribution errors*: Misrepresenting authorship or provenance +* *Access control failures*: Unauthorized access to restricted materials +* *Metadata leaks*: Revealing sensitive information through metadata + +==== Important but Not Emergency + +* *Methodology weaknesses*: Gaps in PROMPT scoring or verification +* *Bias in curation*: Systematic exclusion of perspectives +* *Accessibility barriers*: Features that exclude users +* *Documentation gaps*: Missing information that could lead to misuse + +=== Reporting a Security Issue + +==== For Source Protection Emergencies + +If a source or whistleblower is at risk due to our work: + +*DO NOT* open a public issue *IMMEDIATELY* contact: [Emergency contact - +to be added] + +==== For Other Security Issues + +[arabic] +. *Email*: security@wayfinder.org [to be established] +* Use PGP key [key ID to be added] for sensitive reports +* Include "`SECURITY:`" in subject line +. *Include*: +* Description of the issue +* Steps to reproduce (if applicable) +* Potential impact +* Any suggested fixes +* Whether you want credit when we fix it +. *What happens next*: +* Acknowledgment within 48 hours +* Assessment of severity +* Plan for fix (with timeline) +* Credit in SECURITY.md (if you want it) + +==== Responsible Disclosure + +We ask that you: - Give us reasonable time to fix (90 days for most +issues) - Don’t exploit the vulnerability - Don’t disclose publicly +until we’ve addressed it - Work with us cooperatively + +We promise to: - Acknowledge your report promptly - Keep you updated on +fix progress - Credit you appropriately (if desired) - Not take legal +action against good-faith researchers + +=== Our Security Practices + +==== Data Handling + +*For Research Data*: - Store securely with encryption at rest - Limit +access to need-to-know basis - Document all data handling procedures - +Retain only as long as necessary - Destroy securely when no longer +needed + +*For User Data*: - Collect only what’s necessary - Obtain informed +consent - Allow export and deletion - Never sell or share without +permission - Provide transparency reports + +*For Evidence/Sources*: - Protect confidential sources absolutely - +Verify authenticity before publishing - Maintain chain of custody +documentation - Archive securely for verification - Respect embargo +agreements + +==== Platform Security (When Applicable) + +When we build technical platforms, we will: + +* *Encryption*: +** HTTPS/TLS for all connections +** End-to-end encryption for sensitive communications +** Encryption at rest for stored data +* *Authentication*: +** Multi-factor authentication available +** Strong password requirements +** Regular security audits +* *Access Control*: +** Principle of least privilege +** Regular access reviews +** Audit logging of sensitive operations +* *Updates*: +** Dependency scanning for vulnerabilities +** Regular security updates +** Automated testing for security regressions + +==== Research Ethics + +We follow ethical research practices: + +* *Informed Consent*: Participants know what they’re contributing to +* *IRB Approval*: University research follows institutional review board +processes +* *Privacy Protection*: Personal data minimized and protected +* *Harm Prevention*: Consider potential harms before publication +* *Right to Withdraw*: Participants can remove their contributions + +==== Journalistic Source Protection + +Following best practices from journalism: + +* *Source Anonymity*: Protect confidential sources absolutely +* *Secure Communication*: Encrypted channels (Signal, SecureDrop) +* *Metadata Scrubbing*: Remove identifying information from documents +* *Legal Protection*: Follow journalist-source privilege laws +* *Never Reveal*: Even under legal pressure, protect sources + +=== Vulnerability Disclosure Timeline + +[cols=",,",options="header",] +|=== +|Stage |Timeline |Actions +|Report received |Day 0 |Acknowledge receipt +|Initial assessment |Day 1-3 |Severity classification +|Investigation |Day 4-14 |Understand scope and impact +|Fix development |Day 15-60 |Develop and test fix +|Deployment |Day 61-75 |Roll out fix +|Public disclosure |Day 76-90 |Publish advisory +|=== + +Critical vulnerabilities may be accelerated. + +=== Security Updates + +We publish security updates: + +* *In CHANGELOG.md*: For all security fixes +* *In security advisories*: For significant vulnerabilities +* *To affected users*: Direct notification when relevant + +=== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Status |Security Updates +|0.1.x (current) |Supported |Yes +|Earlier |Pre-release |No +|=== + +=== Security Best Practices for Contributors + +==== If You’re Building Investigations + +* *Protect sources*: Never reveal confidential sources +* *Verify evidence*: Ensure authenticity before publishing +* *Redact PII*: Remove personally identifiable information unless +essential +* *Consider harm*: Think about who could be hurt by publication +* *Secure storage*: Keep working files encrypted + +==== If You’re Building Code + +* *Validate inputs*: Never trust user input +* *Encrypt sensitive data*: Use strong, modern cryptography +* *Follow OWASP Top 10*: Avoid common vulnerabilities +* *Keep dependencies updated*: Regular security patches +* *Review carefully*: Security review for all PRs touching sensitive +areas + +==== If You’re Working with Data + +* *Minimal collection*: Only collect what you need +* *Secure storage*: Encrypt at rest and in transit +* *Access controls*: Limit who can access what +* *Audit trails*: Log access to sensitive data +* *Secure deletion*: Properly destroy when no longer needed + +=== Transparency and Accountability + +==== What We’ll Disclose + +We believe in transparency about: - Security incidents (after +mitigation) - Vulnerabilities (after fixes) - Data breaches +(immediately) - Policy changes - Lessons learned + +==== What We Won’t Disclose + +We protect: - Confidential sources - Unpatched vulnerabilities - +Personal information of affected users - Details that could aid +attackers + +==== Transparency Reports + +We will publish annual transparency reports including: - Number of +security reports received - Number of incidents - Types of issues found +- Average resolution time - Lessons learned and improvements made + +=== Legal Considerations + +==== GDPR Compliance (EU) + +When applicable, we comply with: - Right to access - Right to +rectification - Right to erasure - Right to data portability - Right to +restrict processing + +==== Journalist Privilege + +We assert journalist-source privilege where applicable and will: - +Protect confidential sources - Fight legal attempts to compel disclosure +- Follow ethical journalism standards + +==== Academic Research Ethics + +For academic components: - IRB approval where required - Informed +consent for human subjects - Data protection regulations - Open science +principles + +=== Contact + +* *Security issues*: security@wayfinder.org [to be established] +* *Source protection emergencies*: [Emergency contact - to be added] +* *Privacy questions*: privacy@wayfinder.org [to be established] +* *General questions*: See CONTRIBUTING.md + +=== Acknowledgments + +We thank the security researchers and ethical hackers who help us +improve. Acknowledged contributors: + +* [List to be maintained as reports come in] + +=== Version History + +* *1.0* (2025-11-23): Initial security policy + +''''' + +_This security policy embodies our commitment to transparency, privacy +protection, and epistemic justice. It will evolve based on experience +and community feedback._ + +_See also: link:./CONTRIBUTING.md[CONTRIBUTING.md], +link:./CODE_OF_CONDUCT.md[CODE_OF_CONDUCT.md], +link:./MAINTAINERS.md[MAINTAINERS.md]_ diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9e3a051..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,289 +0,0 @@ - -# Security Policy - -## Our Approach to Security - -Wayfinder is designed around transparency, democratic accessibility, and epistemic justice. Our security model reflects these values: - -- **Transparency by default**: Make processes visible, not hidden -- **Distributed verification**: Multiple independent sources of truth -- **Privacy protection**: Respect dignity of sources and participants -- **Data sovereignty**: Users own their contributions - -## Scope - -This security policy covers: -- Research methodology and data handling -- Source protection and attribution -- User privacy and data ownership -- Platform security (when technical platform exists) -- Community safety (see CODE_OF_CONDUCT.md) - -## What We Consider Security Issues - -### High Severity - -- **Source endangerment**: Exposing confidential sources or whistleblowers -- **Data breaches**: Unauthorized access to user data, investigations, or evidence -- **Evidence tampering**: Unauthorized modification of source materials -- **Doxing**: Publishing private information without consent -- **Platform vulnerabilities**: Security flaws that could compromise data - -### Medium Severity - -- **Privacy violations**: Unintentional exposure of personal information -- **Attribution errors**: Misrepresenting authorship or provenance -- **Access control failures**: Unauthorized access to restricted materials -- **Metadata leaks**: Revealing sensitive information through metadata - -### Important but Not Emergency - -- **Methodology weaknesses**: Gaps in PROMPT scoring or verification -- **Bias in curation**: Systematic exclusion of perspectives -- **Accessibility barriers**: Features that exclude users -- **Documentation gaps**: Missing information that could lead to misuse - -## Reporting a Security Issue - -### For Source Protection Emergencies - -If a source or whistleblower is at risk due to our work: - -**DO NOT** open a public issue -**IMMEDIATELY** contact: [Emergency contact - to be added] - -### For Other Security Issues - -1. **Email**: security@wayfinder.org [to be established] - - Use PGP key [key ID to be added] for sensitive reports - - Include "SECURITY:" in subject line - -2. **Include**: - - Description of the issue - - Steps to reproduce (if applicable) - - Potential impact - - Any suggested fixes - - Whether you want credit when we fix it - -3. **What happens next**: - - Acknowledgment within 48 hours - - Assessment of severity - - Plan for fix (with timeline) - - Credit in SECURITY.md (if you want it) - -### Responsible Disclosure - -We ask that you: -- Give us reasonable time to fix (90 days for most issues) -- Don't exploit the vulnerability -- Don't disclose publicly until we've addressed it -- Work with us cooperatively - -We promise to: -- Acknowledge your report promptly -- Keep you updated on fix progress -- Credit you appropriately (if desired) -- Not take legal action against good-faith researchers - -## Our Security Practices - -### Data Handling - -**For Research Data**: -- Store securely with encryption at rest -- Limit access to need-to-know basis -- Document all data handling procedures -- Retain only as long as necessary -- Destroy securely when no longer needed - -**For User Data**: -- Collect only what's necessary -- Obtain informed consent -- Allow export and deletion -- Never sell or share without permission -- Provide transparency reports - -**For Evidence/Sources**: -- Protect confidential sources absolutely -- Verify authenticity before publishing -- Maintain chain of custody documentation -- Archive securely for verification -- Respect embargo agreements - -### Platform Security (When Applicable) - -When we build technical platforms, we will: - -- **Encryption**: - - HTTPS/TLS for all connections - - End-to-end encryption for sensitive communications - - Encryption at rest for stored data - -- **Authentication**: - - Multi-factor authentication available - - Strong password requirements - - Regular security audits - -- **Access Control**: - - Principle of least privilege - - Regular access reviews - - Audit logging of sensitive operations - -- **Updates**: - - Dependency scanning for vulnerabilities - - Regular security updates - - Automated testing for security regressions - -### Research Ethics - -We follow ethical research practices: - -- **Informed Consent**: Participants know what they're contributing to -- **IRB Approval**: University research follows institutional review board processes -- **Privacy Protection**: Personal data minimized and protected -- **Harm Prevention**: Consider potential harms before publication -- **Right to Withdraw**: Participants can remove their contributions - -### Journalistic Source Protection - -Following best practices from journalism: - -- **Source Anonymity**: Protect confidential sources absolutely -- **Secure Communication**: Encrypted channels (Signal, SecureDrop) -- **Metadata Scrubbing**: Remove identifying information from documents -- **Legal Protection**: Follow journalist-source privilege laws -- **Never Reveal**: Even under legal pressure, protect sources - -## Vulnerability Disclosure Timeline - -| Stage | Timeline | Actions | -|-------|----------|---------| -| Report received | Day 0 | Acknowledge receipt | -| Initial assessment | Day 1-3 | Severity classification | -| Investigation | Day 4-14 | Understand scope and impact | -| Fix development | Day 15-60 | Develop and test fix | -| Deployment | Day 61-75 | Roll out fix | -| Public disclosure | Day 76-90 | Publish advisory | - -Critical vulnerabilities may be accelerated. - -## Security Updates - -We publish security updates: - -- **In CHANGELOG.md**: For all security fixes -- **In security advisories**: For significant vulnerabilities -- **To affected users**: Direct notification when relevant - -## Supported Versions - -| Version | Status | Security Updates | -|---------|--------|------------------| -| 0.1.x (current) | Supported | Yes | -| Earlier | Pre-release | No | - -## Security Best Practices for Contributors - -### If You're Building Investigations - -- **Protect sources**: Never reveal confidential sources -- **Verify evidence**: Ensure authenticity before publishing -- **Redact PII**: Remove personally identifiable information unless essential -- **Consider harm**: Think about who could be hurt by publication -- **Secure storage**: Keep working files encrypted - -### If You're Building Code - -- **Validate inputs**: Never trust user input -- **Encrypt sensitive data**: Use strong, modern cryptography -- **Follow OWASP Top 10**: Avoid common vulnerabilities -- **Keep dependencies updated**: Regular security patches -- **Review carefully**: Security review for all PRs touching sensitive areas - -### If You're Working with Data - -- **Minimal collection**: Only collect what you need -- **Secure storage**: Encrypt at rest and in transit -- **Access controls**: Limit who can access what -- **Audit trails**: Log access to sensitive data -- **Secure deletion**: Properly destroy when no longer needed - -## Transparency and Accountability - -### What We'll Disclose - -We believe in transparency about: -- Security incidents (after mitigation) -- Vulnerabilities (after fixes) -- Data breaches (immediately) -- Policy changes -- Lessons learned - -### What We Won't Disclose - -We protect: -- Confidential sources -- Unpatched vulnerabilities -- Personal information of affected users -- Details that could aid attackers - -### Transparency Reports - -We will publish annual transparency reports including: -- Number of security reports received -- Number of incidents -- Types of issues found -- Average resolution time -- Lessons learned and improvements made - -## Legal Considerations - -### GDPR Compliance (EU) - -When applicable, we comply with: -- Right to access -- Right to rectification -- Right to erasure -- Right to data portability -- Right to restrict processing - -### Journalist Privilege - -We assert journalist-source privilege where applicable and will: -- Protect confidential sources -- Fight legal attempts to compel disclosure -- Follow ethical journalism standards - -### Academic Research Ethics - -For academic components: -- IRB approval where required -- Informed consent for human subjects -- Data protection regulations -- Open science principles - -## Contact - -- **Security issues**: security@wayfinder.org [to be established] -- **Source protection emergencies**: [Emergency contact - to be added] -- **Privacy questions**: privacy@wayfinder.org [to be established] -- **General questions**: See CONTRIBUTING.md - -## Acknowledgments - -We thank the security researchers and ethical hackers who help us improve. Acknowledged contributors: - -- [List to be maintained as reports come in] - -## Version History - -- **1.0** (2025-11-23): Initial security policy - ---- - -*This security policy embodies our commitment to transparency, privacy protection, and epistemic justice. It will evolve based on experience and community feedback.* - -*See also: [CONTRIBUTING.md](./CONTRIBUTING.md), [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md), [MAINTAINERS.md](./MAINTAINERS.md)* diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..0ed864e --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,29 @@ +== TEST-NEEDS.md — im-docs + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current Test State + +[cols=",,",options="header",] +|=== +|Category |Count |Notes +|Test files |1 |Current state +|=== + +=== What’s Covered + +* [x] 1 existing test file(s) + +=== Still Missing (for CRG B+) + +* [ ] Zig FFI tests (if applicable) +* [ ] CI/CD test automation +* [ ] Property-based tests +* [ ] Edge case coverage + +=== Run Tests + +[source,bash] +---- +bash tests/run-all-tests.sh +---- diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index b7a57bb..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,30 +0,0 @@ - -# TEST-NEEDS.md — im-docs - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current Test State - -| Category | Count | Notes | -|----------|-------|-------| -| Test files | 1 | Current state | - -## What's Covered - -- [x] 1 existing test file(s) - -## Still Missing (for CRG B+) - -- [ ] Zig FFI tests (if applicable) -- [ ] CI/CD test automation -- [ ] Property-based tests -- [ ] Edge case coverage - -## Run Tests - -```bash -bash tests/run-all-tests.sh -``` diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 88% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index 0dbe370..d82efdf 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,15 +1,8 @@ - - - +== Wayfinder (im-docs) — Project Topology -# Wayfinder (im-docs) — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ COMMUNITIES │ │ (Activists, Academics, Journalists) │ @@ -50,11 +43,11 @@ Copyright (c) Jonathan D.A. Jewell │ Justfile Automation .machine_readable/ │ │ Documentation Hub 0-AI-MANIFEST.a2ml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CONCEPTUAL FRAMEWORK @@ -75,25 +68,26 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ██████░░░░ ~60% Conceptual foundation 100% stable -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Cognitive Science ───► PROMPT Model ───► Boundary Object ──► Wisdom │ │ │ │ ▼ ▼ ▼ ▼ Attention Limits ──► Progression ──────► Investigation ──► Decision -``` +.... -## Update Protocol +=== Update Protocol This file is maintained by both humans and AI agents. When updating: -1. **After completing a component**: Change its bar and percentage -2. **After adding a component**: Add a new row in the appropriate section -3. **After architectural changes**: Update the ASCII diagram -4. **Date**: Update the `Last updated` comment at the top of this file +[arabic] +. *After completing a component*: Change its bar and percentage +. *After adding a component*: Add a new row in the appropriate section +. *After architectural changes*: Update the ASCII diagram +. *Date*: Update the `+Last updated+` comment at the top of this file -Progress bars use: `█` (filled) and `░` (empty), 10 characters wide. -Percentages: 0%, 10%, 20%, ... 100% (in 10% increments). +Progress bars use: `+█+` (filled) and `+░+` (empty), 10 characters wide. +Percentages: 0%, 10%, 20%, … 100% (in 10% increments). diff --git a/claude.adoc b/claude.adoc new file mode 100644 index 0000000..5ddc40c --- /dev/null +++ b/claude.adoc @@ -0,0 +1,1129 @@ +== Wayfinder: Epistemic Infrastructure for Journalism + +=== Project Vision + +*Wayfinder* is a heutagogic capability development pathway and +interactive journalism framework designed to transform journalism from +static truth-claims into navigable knowledge ecosystems. It addresses +the fundamental challenge that data is outpacing knowledge, +intelligence, and wisdom by making epistemological navigation itself the +primary journalistic product. + +==== Core Thesis + +We haven’t moved from "`Truth to Post-Truth`" but from an era where +knowledge systems were simpler to one where they’re overwhelmed by data +velocity. The solution isn’t faster fact-checking—it’s making +truth-discovery processes transparent and navigable, not hidden behind +editorial authority. + +=== Conceptual Foundations + +==== 1. The Knowledge Navigation Problem + +*Traditional Journalism*: "`Here’s what happened.`" *Wayfinder +Approach*: "`Here’s the evidence ecosystem. Navigate it. Understand how +we know.`" + +This directly addresses that: - Information velocity has exceeded +sense-making capacity - Trust in epistemic authorities has collapsed +(often for good reasons) - Different communities have developed +different truth-testing procedures - No shared infrastructure exists for +collective intelligence + +==== 2. Boundary Objects Theory (Susan Leigh Star) + +Wayfinder investigations function as *boundary objects* that: - Maintain +coherence across different communities - Adapt to local needs without +losing identity - Enable coordination without requiring consensus - Make +visible what each community values - Create shared infrastructure while +respecting difference + +*Example*: The same evidence structure serves: - *Activists*: Tool for +mobilization ("`What action should I take?`") - *Policymakers*: Decision +support ("`What are trade-offs?`") - *Academics*: Research resource +("`What’s the methodology?`") - *Skeptics*: Challenge mechanism ("`Show +me what’s wrong`") - *Affected Communities*: Validation ("`How does this +affect people like me?`") - *Journalists*: Living investigation +("`What’s the story?`") + +All work with the SAME evidence but interpret/use it differently. This +bridges post-truth by creating coordination infrastructure, not forcing +consensus. + +==== 3. PROMPT Framework + +**P**rovenance - Who said it? What’s their track record? **R**elevance - +Does this actually address the claim? **O**bjectivity - What biases +exist? Are they disclosed? **M**ethods - How was this evidence gathered? +Is it sound? **P**erspective - What viewpoints are represented? What’s +missing? **T**imeliness - Is this current? Has it been superseded? + +Each investigation assigns PROMPT scores to claims, making epistemic +evaluation transparent. + +==== 4. Data → Knowledge → Intelligence → Wisdom Pipeline + +Traditional journalism conflates all four levels. Wayfinder separates +and makes each navigable: + +* *Data Layer*: Raw evidence, fully accessible +* *Knowledge Layer*: Structured claims with PROMPT analysis (what we can +reliably say) +* *Intelligence Layer*: Pattern recognition, contradiction +identification, gap analysis (what connections mean) +* *Wisdom Layer*: Practical reasoning for decision-making (what to do +about it) + +=== Architecture: Living Stories as Knowledge Graphs + +==== Core Components + +===== 1. The Claim Layer + +* Every piece starts with explicit, testable claims +* Each claim carries PROMPT scores visible to readers +* Claims are nodes that link to their evidence networks +* Statistical uncertainty is native (Dempster-Shafer intervals, not +false certainty) + +===== 2. The Evidence Substrate + +* Primary sources become explorable objects, not cited footnotes +* Korsakow-style "`smallest narrative units`" but for journalism: +** Original documents (OCR’d, searchable, annotatable) +** Interview segments (timestamped, transcribed, cross-referenced) +** Statistical data (interactive, methodology exposed) +** Expert analysis (credentials visible, conflicts flagged) +** Contradictory evidence explicitly included + +===== 3. The Methodology Transparency Layer + +* Show editorial process: "`We contacted 15 sources. Here’s who +responded, declined, or was unreachable`" +* Expose reasoning chains: Not "`experts say X`" but "`Expert A +(credentials, biases) argues X because Y, based on methodology Z`" +* Make PROMPT analysis visible +* Statistical reasoning exposed: Dempster-Shafer calculations, +confidence intervals, assumptions + +===== 4. The Multi-Perspectival Navigation System + +* Readers choose paths through evidence based on their questions +* Not "`choose your own truth`" but "`explore from different epistemic +starting points`" +* Shows where perspectives converge (strong evidence) and diverge +(genuine uncertainty vs. motivated reasoning) + +===== 5. The Collaborative Knowledge Layer + +* Readers with expertise can annotate (credentials/reputation visible) +* Wikipedia’s talk pages meets peer review +* New evidence can be submitted, triggering re-analysis +* Story evolves as living document, version history fully transparent + +=== Cognitive Science & Design Principles + +==== The Cognitive Load Paradox + +*Problem*: Interactive systems can create cognitive overload when trying +to reduce epistemic confusion. + +*Evidence*: - Working Memory Limits (Cowan, 2001): ~4 chunks actively +processed - Choice Paralysis (Schwartz): More options → decision +paralysis - Illusion of Explanatory Depth: People think they understand +better when they can interact + +*Design Mitigations*: + +[arabic] +. *Progressive Disclosure Architecture* +* Start with 3-5 essential claims maximum +* Each click reveals one level deeper, not everything +* "`You’re at depth 2 of 5`" - make navigation cost visible +* Exit ramps at every level +. *Cognitive Scaffolding Through Curated Paths* +* Offer 3-4 "`recommended paths`" (guided museum tours) +* Only after completing one: "`Explore freely`" +* Respects spacing effect (distributed practice beats cramming) +. *Meta-Cognitive Prompts* +* "`Before exploring, what would change your mind?`" +* "`You’ve spent 15 mins on confirming evidence, 2 mins contradicting - +explore more?`" +* Make reader’s cognitive strategy visible to themselves +. *Active Retrieval Integration* +* Every 3-5 steps: "`What’s your understanding so far?`" +* Converts navigation into learning, not just browsing + +==== The Motivated Reasoning Problem + +*Problem*: Confirmation bias + selective navigation = echo chambers +within your own tool. + +*Evidence*: - Kahan’s Cultural Cognition: People process evidence +through identity-protective lenses - Myside Bias: Better at finding +flaws in opposing arguments - Backfire Effect: Contradicting evidence +can strengthen prior beliefs + +*Design Mitigations*: + +[arabic] +. *Transparent Navigation Analytics* +* "`You’ve viewed 12 pieces of evidence. 10 support X, 2 challenge it`" +* "`This pattern is common for people who believe X`" (reflective, not +judgmental) +* Gamification: "`Completionist badge: Explored all major perspectives`" +. *Empathy-First Contradictory Evidence* +* Before showing contradictions, humanize them +* "`People who believe Y often do so because…`" (steel man, not straw +man) +. *Pre-Commitment Mechanisms* +* "`What evidence would change your mind?`" (before seeing evidence) +* Creates psychological commitment to epistemic openness +. *Collaborative Annotation with Adversaries* +* Partner readers with opposing views (opt-in) +* Explore together, see agreements/disagreements +* Social interaction reduces abstraction, increases humility + +==== The Trust Calibration Challenge + +*Problem*: How much to trust the system? Too much = uncritical +acceptance. Too little = ignores good evidence. + +*Design Mitigations*: + +[arabic] +. *Calibrated Confidence Display* +* Not just "`PROMPT score 0.7`" but "`Similar to [known +reliable/unreliable] stories`" +* "`Stories with this evidence structure: X% accuracy rate`" +. *Editor’s Uncertainty Log* +* "`I couldn’t verify X despite Y attempts`" +* "`This source has Z credibility because…`" +* Humanizes process, shows effort +. *Competing Analyses* +* For controversial topics: 2-3 independent journalistic teams +* Same evidence base, different PROMPT analyses +* Show convergence (high confidence) vs. divergence (genuine +uncertainty) + +=== Bio-Psycho-Social-Technical Systems Analysis + +==== Biological Layer: Attention & Perception + +*Constraints*: - Attentional Blink: Miss second target if 200-500ms +after first - Change Blindness: Miss large changes if attention +elsewhere - Visual Processing: ~10M bits/sec input, ~40 bits/sec +conscious + +*Design Implications*: - Max 3 active interactive zones per screen - Use +motion sparingly (draws involuntary attention) - Critical info +persistent, not transient - Mobile-first (attention more fractured) - +Dual-coding (Paivio): Present claims verbally AND visually + +==== Psychological Layer: Identity & Sensemaking + +*Key Insight*: People protect coherent self-narratives, not just +evaluate evidence. + +*Threats*: - System makes users feel stupid → defensive rejection - +Violates group identity → social cost too high - Creates existential +anxiety → denial/avoidance + +*Design Interventions*: + +[arabic] +. *Face-Saving Architecture* +* Never "`You were wrong`" → "`Evidence changed`" or "`Additional +context emerged`" +* "`Smart people disagree`" (normalize uncertainty) +* Celebrate updating: "`Epistemic flexibility badge`" +. *Identity-Safe Framings* (Kahan) +* Don’t make issues identity-diagnostic if avoidable +* Frame climate as "`energy security + innovation`" not "`believe +science or be denier`" +* Let users enter from their values, arrive at evidence +. *Narrative Coherence Support* +* People need stories, not just data +* Include paths maintaining coherence while updating beliefs +* "`How to change your mind without losing your story`" + +==== Social Layer: Collective Sensemaking + +*Opportunities*: + +[arabic] +. *Visible Cross-Cutting Exposure* +* "`People who share view on X often agree on Y, disagree on Z`" +* Show unexpected alliances (libertarians + progressives on +surveillance) +. *Collaborative Investigation Features* +* Small groups (4-6) explore together +* Mix of perspectives encouraged +* Shared annotation creates common ground +. *Bridging Figures* +* Highlight experts/journalists trusted across divides +* Not "`neutral`" but "`respected by multiple sides`" +. *Network Analysis Transparency* +* "`1M people shared this. Here’s who: [demographics]`" +* "`Went viral in networks X, Y, but not Z - why?`" + +==== Technical Layer: Infrastructure Requirements + +*Critical Requirements*: + +[arabic] +. *Accessibility* (Democratic accessibility principle) +* Screen reader compatible +* Text-only fallback +* Low-bandwidth version +* Translatable (i18n from day one) +. *Archival Permanence* +* Static site generation where possible +* No link rot (archive all sources) +* Version control everything +* IPFS/Arweave for permanence? +. *Algorithm Transparency* +* Any ranking/sorting explainable +* No hidden personalization (or fully disclosed) +* Open source where possible +. *Data Sovereignty* +* Users own annotations/navigation data +* Export anytime +* No surveillance capitalism + +=== SWOT Analysis + +==== Strengths + +* *Epistemological Rigor*: PROMPT + philosophical framework provides +theoretical foundation +* *Handles Genuine Uncertainty*: Embraces complexity honestly, doesn’t +pretend certainty +* *Scalable Complexity*: More complex topics → richer navigation, not +just longer articles +* *Process Transparency*: Shows work, builds trust through visibility +* *Living Documents*: Updates as evidence evolves without +"`corrections`" shame +* *Multi-Perspectival Without Relativism*: Different viewpoints without +"`all views equal`" +* *Educational Value*: Users learn epistemic literacy by doing + +==== Weaknesses + +* *Production Cost*: 10x more work than traditional article (initially) +* *Requires New Skills*: Journalists need training in knowledge +architecture, stats, design +* *User Learning Curve*: Audiences trained on passive consumption +* *Can’t Cover Breaking News*: Too slow for "`what happened today`" +* *Vulnerability to Bad Faith*: Sophisticated actors could game the +system +* *Maintenance Burden*: Living documents need tending +* *Cognitive Overhead*: Risks overwhelming users despite best design +* *Measurement Difficulty*: Hard to prove it’s working + +==== Opportunities + +* *Institutional Support*: Knight Foundation, Craig Newmark +Philanthropies fund innovation +* *Academic Partnerships*: PhD programs need practical outputs +* *NUJ Endorsement*: Professional legitimacy +* *Open Source Community*: Build in public, attract contributors +* *Journalism Crisis*: Desperation creates openness to experiment +* *Platform Exhaustion*: Audiences tired of social media epistemology +* *AI Literacy Movement*: Growing appetite for understanding information +systems +* *Policy Interest*: Governments seeking misinformation solutions +* *Educational Adoption*: Universities teach media literacy with it +* *i-Docs Connection*: Built-in community and expertise + +==== Threats + +* *Economic Reality*: No obvious business model +* *Platform Competition*: Social media optimized for engagement, not +truth +* *Attention Economy*: Fighting for scarce cognitive resource +* *Political Resistance*: Some actors benefit from confusion +* *Technical Debt*: Building custom systems vs. commercial tools +* *Perfectionism Trap*: Can’t launch until "`perfect`" +* *Scope Creep*: Feature requests could bloat system +* *Burnout Risk*: One person with PhD to finish +* *Coordination Costs*: Multi-institution collaboration is hard +* *Measurement/Proof Problem*: Hard to prove impact, may lose funding + +=== Heutagogic Learning Pathway + +==== Core Principle + +Journalists are demoralized, seeing "`the end of journalism.`" They need +self-determined learning with rapid proof-of-value through mastery +experiences. + +*Not*: "`Here’s a new system to learn!`" *Instead*: "`You have +capabilities MORE valuable in information chaos. Build something that +proves it.`" + +==== The Four Capability Levels + +===== Level 1: "`Skeptical Journalist`" → Evidence Mapper + +*Time*: 4-8 hours *Output*: Single evidence-mapped claim *Skill*: +Provenance auditing + +*Challenge*: "`Take one claim you’re reporting. Just one. Map its +evidence.`" + +*Process*: 1. Choose claim (something you’re working on anyway) 2. List +evidence (what you already have) 3. Score provenance (P from PROMPT - +just this dimension) 4. Visualize (simple text list or hand-drawn +sketch) 5. Reflect: "`What did I discover?`" + +*Reward*: - Stronger sourcing for your article - Spotted gaps to fill - +Better editor pitches: "`Verified through X independent sources`" - More +rigorous defense of reporting + +*Portfolio*: "`I can identify strongest/weakest evidence parts`" + +===== Level 2A: "`Methodological Journalist`" → Process Documentarian + +*Time*: 8-12 hours *Output*: Methodology transparency appendix *Skill*: +Scientific reasoning + +*Challenge*: "`Show HOW you investigated, not just WHAT you found.`" + +*What You Build*: Methodology appendix documenting: - Research questions +(primary + secondary) - Sources consulted (attempted, successful, +declined, unavailable) - Documents reviewed (primary sources, secondary +analysis, contradictory evidence) - Methodological choices (why these +sources? what’s missing? assumptions? contradictions?) - Confidence +assessment (evidence strength, certainty level, what would change this?) +- Timeline (when you discovered what) + +*Reward*: - Editors love rigor, reduces liability - Builds reader trust +- Improves quality (notice gaps while reporting) - Professional +development - Competitive advantage + +*Portfolio*: "`I practice transparent methodology journalism`" + +===== Level 2B: "`Statistical Journalist`" → Uncertainty Communicator + +*Time*: 6-10 hours *Output*: Claims with honest confidence intervals +*Skill*: Statistical reasoning for journalism + +*Challenge*: "`Replace false certainty with honest uncertainty that’s +more trustworthy.`" + +*Example Transformation*: - *Bad*: "`Inflation is 5%.`" - *Good*: +"`Inflation reported at 5%, but: - Uses CPI methodology (excludes X) - +Margin of error ±0.2% - National average (regional: 3.8%-6.3%) - Doesn’t +capture lived experience of [groups]`" + +*Reward*: - More accurate than journalists pretending certainty - +Readers trust you more (research confirms) - Avoid errors (understanding +uncertainty → fewer corrections) - Future-proof (where journalism must +go) + +*Portfolio*: "`I communicate uncertainty responsibly`" + +===== Level 3: "`Interactive Journalist`" → Knowledge Architect + +*Time*: 20-40 hours (spread over weeks) *Output*: Fully interactive +evidence-based investigation *Skill*: Non-linear narrative design + +*Challenge*: "`Create a living investigation readers navigate, not just +read.`" + +*Components* (modular, choose what you need): - Core Claims Graph (3-7 +main claims) - Evidence Library (all sources, categorized) - Methodology +Transparency Page - Multiple Entry Points (3-4 perspectives) - +Statistical Reasoning Exhibits (for numerical claims) - Contradiction +Acknowledgment (what doesn’t fit) - Update Log (as story evolves) - +Contribution Interface (how others add evidence) + +*Three Paths*: - *Path A*: Convert existing story - *Path B*: New +investigation from scratch - *Path C*: Collaborative (2-3 journalists, +shared evidence base) + +*Reward*: - Unique portfolio piece (no other journalist has this) - +Demonstrates future skills - Actual impact (readers understand complex +topics better) - Professional recognition (conferences, awards, jobs) - +Personal satisfaction + +*Critical*: YOU choose the topic. Your passion = better output. + +===== Level 4: "`Systems Journalist`" → Epistemic Infrastructure Builder + +*Time*: Ongoing practice *Output*: Multiple investigations, teaching +others, building tools *Skill*: Meta-capability (learning to learn) + +*Challenge*: "`You’ve mastered the method. Now evolve it.`" + +*Activities* (self-chosen): - *Build*: Create new tools/templates for +community - *Teach*: Run workshops for other journalists - *Research*: +Write about methodology, publish findings - *Advocate*: Push for +institutional adoption - *Innovate*: Invent new approaches to epistemic +problems + +*Reward*: - You’re a pioneer (defining journalism’s future) - You’re +employable (rare, valuable skills) - You’re autonomous (work +independently) - You have meaning (solving real problems) - You build +legacy (training next generation) + +==== Heutagogic Architecture: Self-Determination Mechanisms + +===== 1. Multiple Entry Points + +Quiz: "`Which sounds like you?`" - "`I’m skeptical but curious`" → Level +1 - "`I want to be more rigorous`" → Level 2A - "`I’m bad at numbers but +want to improve`" → Level 2B - "`I want to build something new`" → Level +3 - "`I already do some of this`" → Skip-ahead assessment + +===== 2. Self-Paced Progression + +* No deadlines, cohorts, or pressure +* "`Most journalists spend 6 hours at Level 1`" +* "`Do this in one day or over a month`" +* "`Pause and return anytime`" +* "`Repeat levels to practice`" + +===== 3. Choice Architecture + +At every decision point: - Show 3-4 options - Show consequences (what +you’ll learn/build) - Show escape routes ("`Not ready? Try this +instead`") - Show connections ("`Relates to X you already know`") + +===== 4. Reflection Prompts (Meta-Learning) + +After each level: - "`What was harder than expected?`" - "`What was +easier?`" - "`What will you do differently?`" - "`What did you learn +about your own learning?`" + +Builds capability (not just competency). + +===== 5. Peer Learning (Optional) + +* Buddy system: Pair journalists at same level +* Show and tell: Share work-in-progress +* Critique circles: 3-4 people review each other +* Expert office hours: Weekly drop-in + +All optional. Introverts can learn alone. + +===== 6. Portfolio Building (Visible Progress) + +Each journalist maintains capability portfolio showing: - Evidence +mapping examples - Methodology transparency exhibits - Statistical +journalism pieces - Interactive investigations - Tools created - Skills +checklist + +LinkedIn-able, hireable, provable value. + +=== "`Gamified by Results`" Reward System + +==== Intrinsic Rewards (What Actually Motivates Professionals) + +[arabic] +. *Competence* (Mastery Experience) +* "`I can do something I couldn’t before`" +* Each level proves new capability +* Feedback immediate and real +. *Autonomy* (Self-Direction) +* "`I chose this path`" +* No one forced me +* I control pace and focus +. *Purpose* (Meaningful Impact) +* "`This matters`" +* Builds better journalism +* Serves democracy +* Helps other journalists +. *Progress* (Visible Growth) +* Portfolio shows trajectory +* Compare early vs. recent work +* "`I’ve come far`" + +==== Extrinsic Rewards (Secondary but Useful) + +[arabic] +. *Professional Recognition* +* Certificate: "`Epistemic Journalism Practitioner`" +* "`Knowledge Architect`" credential (backed by NUJ?) +* Listed in public directory +* Speaking opportunities +. *Economic Value* +* "`I can charge more for this work`" +* "`I got hired because of my portfolio`" +* "`My pitches succeed more often`" +. *Peer Status* +* "`Other journalists ask me to teach them`" +* "`I’m invited to conferences`" +* "`Editors request me specifically`" +. *Competitive Advantage* +* "`I have skills others don’t`" +* "`I’m future-proof`" +* "`AI can’t do what I do`" + +==== Results-Based "`Unlocks`" (Not Arbitrary Points) + +*After Level 1*: - "`Evidence mapper`" credential - Access to private +journalist community - Work featured in showcase - Can mentor newcomers +(if you want) + +*After Level 2A or 2B*: - "`Methodological journalist`" credential - +Advanced templates and tools - Guest post on methodology blog - Can +contribute to tool development + +*After Level 3*: - "`Knowledge architect`" credential - Investigation in +featured gallery - Conference speaking opportunities - Can apply for +grants/funding - Job board access (orgs seeking these skills) + +*After Level 4*: - "`Epistemic infrastructure builder`" credential - +Co-author research papers - Shape future of system - Revenue share from +tools you create + +Each unlock genuinely valuable, not symbolic. + +=== Demoralization → Hope Transition Strategy + +==== Initial Contact: Meet Them in Their Despair + +*Don’t start with*: "`Here’s a new system to learn!`" + +*Start with*: "`Journalism isn’t dying. It’s evolving. You have the +capability to lead that evolution.`" + +==== The Pitch (for demoralized journalists) + +“You’re right that traditional journalism is struggling. But the problem +isn’t journalism—it’s that we’re using 20th-century methods for +21st-century information chaos. + +What if the skills you already have—investigation, verification, source +development—are actually MORE valuable now, not less? What if you could +develop capabilities that AI can’t replicate and audiences desperately +need? + +I’m building a pathway for journalists to develop these capabilities. +Not a course. Not a tool. A self-directed learning journey where you +build real investigations that demonstrate these skills while you learn +them. + +It takes 4 hours to see if this resonates. If it doesn’t, you’ve lost +nothing. If it does, you’ve started building a portfolio that makes you +uniquely valuable. + +Want to try?” + +==== Early Win Engineering (Critical First 8 Hours) + +*Hour 1-2*: Watch examples - See 3 interactive investigations - Notice +what’s different - "`Could I build this?`" + +*Hour 3-6*: Build Level 1 evidence map - Use story you’re already +working on - Apply PROMPT to one claim - See value immediately + +*Hour 7-8*: Share and reflect - Show to colleague or editor - Get +feedback - Decide: continue or not? + +*Success metric*: "`After 8 hours, do you think: '`This might be +valuable`' vs. '`This is pointless`'`" + +If yes → They’ll self-direct from there. If no → Wrong time or wrong fit +(no pressure). + +==== Community-Building (Combat Isolation) + +*Weekly Sync* (Optional): - 90-minute video call - Show and tell: +"`Here’s what I built`" - Problem-solving: "`Here’s where I’m stuck`" - +Teaching: "`Here’s what I learned`" + +*Async Community*: - Forum/Discord/Slack - Share work-in-progress - Ask +questions - Celebrate achievements + +*In-Person Gatherings* (Quarterly): - One-day workshop - Deep dive on +advanced topics - Guest speakers - Networking + +*The Magic*: Demoralized journalists discover they’re not alone. Others +are figuring this out too. + +=== Technical Implementation + +==== Phase 1: Proof of Concept (NOW - 3 months) + +*Tools You Can Use Immediately*: + +[arabic] +. *Obsidian Publish + Dataview Plugin* +* Graph database-lite (markdown files with frontmatter) +* Bidirectional links (evidence ↔ claims) +* Query language for dynamic views +* Publishable as static site +* Cost: $8/month hosting +* Advantage: Local-first, portable, no vendor lock-in +. *TiddlyWiki with Stroll Plugin* +* Single-file wiki (3MB, runs offline) +* Backlinks, transclusion, tags +* Zettelkasten-style navigation +* Cost: Free, self-hostable +* Advantage: Archival permanence, zero dependencies +. *Notion Public Pages* +* Databases with relations +* Multiple views (list, gallery, timeline) +* Embeds, comments +* Cost: Free tier workable +* Disadvantage: Proprietary, not archival + +*Prototype Structure*: + +Choose ONE complex story (e.g., "`UK inflation crisis 2023`") + +Create: - 5-7 core claims (nodes) - 20-30 evidence pieces (documents, +interviews, data) - 3 curated navigation paths - PROMPT scores for each +claim - Methodology transparency page - Multiple entry points + +Measure: - Time to navigate - Paths taken - Where users get stuck - +Comprehension tests - Attitude change + +Test With: - 5 NUJ journalists (can they build it?) - 5 academics (do +they trust it?) - 5 activists (do they find it useful?) - 5 skeptics +(can they critique it?) - 5 "`normal`" readers (is it accessible?) + +==== Phase 2: Custom Platform (3-9 months) + +If proof-of-concept works: + +*Technology Stack* (Respecting preferences): + +Backend: - Python (FastAPI or Django) - PostgreSQL (with pg_graphql for +graph queries) - MinIO (S3-compatible storage) - Redis (caching) - +Celery (background tasks) + +Frontend: - SvelteKit (better DX than React, progressive enhancement) - +TailwindCSS (utility-first styling) - D3.js (evidence graph +visualization) - Marked (Markdown → HTML) + +Infrastructure: - Podman for containerization - GitLab CI/CD - +Self-hosted or Hetzner (EU data sovereignty) + +Key Features: - Evidence graph editor - PROMPT scoring workflow - +Multi-path navigation - Annotation system - Version control (git-like +for content) - Export/archive functionality + +*Progressive Enhancement Philosophy*: - Works with JavaScript disabled +(readable, navigable) - Enhanced with JS (interactive graphs, +animations) - Respects prefers-reduced-motion - Degrades gracefully + +==== Phase 3: Ecosystem Building (9-18 months) + +*Community Infrastructure*: + +[arabic] +. *Journalist Training Program* +* 3-day intensive: epistemology, PROMPT framework, tool usage +* Partner with NUJ for certification +* Create "`Knowledge Architect`" credential +. *Open Source Tools* +* PROMPT scorer (standalone) +* Evidence graph generator +* Statistical reasoning visualizer +* Release as modular components +. *Example Investigations* (Portfolio) +* Climate: "`What do we know about 1.5°C targets?`" +* Economics: "`UK inflation causes: competing explanations`" +* Health: "`Long COVID evidence assessment`" +* Local: "`Town planning controversy: all evidence`" +* Each demonstrates different features +. *Academic Integration* +* Partner with journalism schools +* PhD students do investigations as dissertations +* Published in new "`Journal of Interactive Investigations`" +. *Funding Diversification* +* Knight Foundation grants (they fund exactly this) +* Omidyar Network (investigative journalism) +* European Media & Information Fund +* University research funding +* Institutional subscriptions (news orgs pay to use platform) + +==== Phase 4: Scaling & Sustainability (18+ months) + +*Network Effects*: + +[arabic] +. *Evidence Commons* +* Investigations link to each other’s evidence +* Build shared fact base +* Reduces duplication +. *Methodology Standardization* +* PROMPT becomes industry standard +* Like "`fact-checked`" but deeper +* "`PROMPT-verified investigation`" +. *API & Embeds* +* Other news sites embed your evidence graphs +* NPR story links to your evidence infrastructure +* Create distributed ecosystem +. *Institutional Adoption* +* BBC produces one interactive investigation +* Guardian has "`Interactive Evidence`" section +* ProPublica uses platform for exposés + +=== Critical Success Factors + +==== 1. Start Small, Prove Value + +* One story, done excellently >> ten stories half-done +* Measure impact: comprehension, trust, behavior change +* Publish methodology + results + +==== 2. Build in Public + +* Document everything on GitLab +* Weekly dev logs +* Open source from day one +* Invite collaboration + +==== 3. Respect Cognitive Limits + +* Test with real users constantly +* Simplify relentlessly +* Kill features that confuse + +==== 4. Maintain Epistemic Humility + +* Your system can be wrong +* Show its limitations explicitly +* Welcome criticism +* Update based on evidence + +==== 5. Create Beautiful Failures + +* Some investigations will reveal: "`We don’t know`" +* This is success, not failure +* Normalize uncertainty + +==== 6. Partner, Don’t Compete + +* Not trying to replace traditional journalism +* Complementary tool +* Collaborate with news orgs + +=== Boundary Object Implementation Strategy + +*Make This EXPLICIT in Design*: + +*Homepage Text*: + +“This investigation serves different purposes for different communities. +Choose your path: + +* *Want to take action?* See implications and what you can do +* *Making policy?* Explore trade-offs and decision frameworks +* *Researching?* Dive into methodology and data +* *Skeptical?* Challenge our evidence and reasoning +* *Affected by this?* Find relevant local impacts +* *Fellow journalist?* See sources and newsworthiness + +All paths use the same evidence. All are valid. You can switch paths +anytime.” + +This normalizes plurality while maintaining evidential unity. + +=== PhD Integration + +This IS the thesis: + +*Literature Review*: Heutagogy, cognitive ergonomics, boundary objects, +epistemology + +*Design Research*: Building and testing the system + +*Action Research*: Working with practicing journalists + +*Evaluation*: Measuring impact on practice + +*Theoretical Contribution*: "`Pragmatic epistemology for public +communication`" instantiated + +==== PhD Outputs: + +* Thesis: Theory + methodology + findings +* Working system: Demonstrates theory in practice +* Trained journalists: Evidence of impact +* Published investigations: Exemplars +* Tools/frameworks: Transferable artifacts + +==== Nico Carpentier Alignment + +Perfectly aligns with participatory communication theory: - Journalists +as co-creators (not just authorities) - Audiences as active participants +(not passive consumers) - Democratic accessibility through capability +development - Pre-Truth to Truth argument embedded (system shows how +truth is constructed) - Boundary objects enable coordination without +consensus + +=== Implementation Timeline + +==== Month 1-2: Foundation + +* Build Level 1 materials +* Create 2 example investigations +* Set up basic website +* Recruit 5 beta testers (NUJ contacts) + +==== Month 3-4: First Cohort + +* 10-15 journalists go through Level 1 +* Gather feedback +* Iterate materials +* Build Level 2A materials + +==== Month 5-6: Expansion + +* Launch Level 2B +* First Level 3 investigations produced +* Case studies published +* Media coverage + +==== Month 7-9: Community + +* Self-organizing study groups +* First Level 4 practitioners +* Tools being shared +* Institutional interest + +==== Month 10-12: Sustainability + +* Revenue model established +* Community mostly self-managing +* Focus on research/innovation +* System works autonomously + +=== The Philosophical Payoff + +==== Thesis Argument Strengthens: + +*Not*: "`We fell from Truth to Post-Truth`" + +*But*: "`We evolved from simple epistemology to complex epistemology +without building the infrastructure`" + +==== Wayfinder IS That Infrastructure + +It embodies: - PROMPT framework (practical epistemology) - +27-philosopher synthesis (theoretical depth) - Statistical methods +(honest uncertainty) - Democratic accessibility principle (epistemic +justice) - The i-docs insight (navigation over narration) - Boundary +objects theory (coordination without consensus) + +It’s not just a tool. It’s a working model of *pragmatic epistemology +for public communication*. + +And crucially: *It’s buildable now*. With existing technologies. With +existing skills and networks. Within PhD timeframes. + +=== Next Steps: Starting This Week + +==== Week 1: + +* Document Level 1 pathway (8-10 pages) +* Create evidence mapping template +* Build one example investigation (use existing project) + +==== Week 2: + +* Share with 3 journalist friends +* "`Will you try this for 4 hours and give me feedback?`" +* Iterate based on responses + +==== Week 3: + +* Build simple website (GitLab Pages) +* Write recruitment pitch +* Post in NUJ channels + +==== Week 4: + +* First 5-10 participants start +* Support them through Level 1 +* Document what works/doesn’t + +*You’re 4 weeks from proof-of-concept.* + +''''' + +=== Branding & Messaging + +==== Primary Name: Wayfinder + +*Why This Works*: + +[arabic] +. *Solves Demoralization*: "`You’re not obsolete—you’re a Wayfinder. +People need guides who show them HOW to navigate complexity, not just +WHAT to believe.`" +. *Boundary Object Name*: Different communities hear what they need: +* Journalists: "`I help people find their way through complex stories`" +* Academics: "`Wayfinding through epistemic complexity`" +* Funders: "`Teaching information navigation skills`" +* Public: "`Guides who show you how to understand complex issues`" +. *Scales Beautifully*: +* The investigations: "`Wayfinder investigations`" +* The journalists: "`I’m a Wayfinder`" or "`Wayfinder journalist`" +* The training: "`Wayfinder learning pathway`" +* The credentials: "`Certified Wayfinder`" / "`Wayfinder practitioner`" +. *Gamification-Friendly*: +* Level 1: Apprentice Wayfinder +* Level 2: Journeyman Wayfinder +* Level 3: Master Wayfinder +* Level 4: Wayfinder Architect + +==== Tagline Options: + +* "`Wayfinder: Navigate complexity, build understanding`" +* "`Wayfinder: Journalism for the journey from data to wisdom`" +* "`Wayfinder: Guides through information complexity`" +* "`Wayfinder: Building navigable knowledge`" + +==== Elevator Pitch: + +"`Wayfinder trains journalists to create navigable +investigations—living, interactive evidence structures that help readers +find their way through complex, contested topics. It’s not just better +journalism; it’s journalism rebuilt for epistemic complexity.`" + +==== For Demoralized Journalists: + +"`You’re not obsolete. You’re needed more than ever—but as Wayfinders, +not gatekeepers. People need guides who show them HOW to navigate +complexity, not just WHAT to believe. Wayfinder gives you the +capabilities to be that guide.`" + +''''' + +=== Institutional Angle (For Sustainability) + +==== Pitch to News Organizations: + +“Your journalists are demoralized because they feel obsolete. They’re +not. But they need new capabilities. + +For [£X/month per journalist], we provide: - Self-paced capability +development - Tools and templates - Community support - Portfolio +building - Credentialing + +Results: - Higher-quality investigations - Methodological rigor (reduces +liability) - Competitive advantage in market - Improved morale and +retention - Future-proof skills + +No mandates. Journalists opt-in. You see who’s engaged.” + +This funds development while serving journalists. + +''''' + +=== Platform: Minimal Viable Infrastructure + +*Core*: Simple website (Hugo/Jekyll static site) *Content*: Markdown +files (portable, future-proof) *Hosting*: GitLab Pages (free, version +controlled) *Learning paths*: Embedded in content, not LMS *Community*: +Discord or Discourse (free tiers) *Portfolio hosting*: Personal +GitHub/GitLab pages + +*Total cost*: ~£0-20/month at start + +''''' + +=== Content Creation Strategy: Build With, Not For + +*You create*: - Level 1 materials (evidence mapping basics) - Framework +documentation (PROMPT) - Example investigations (2-3 different topics) - +Templates (Notion, Obsidian, Markdown) + +*Community creates* (Level 4 participants): - Additional examples - +Specialized tools - Domain-specific guides - Translations - Improvements + +This scales WITHOUT you doing everything. + +''''' + +=== Measuring Success + +==== Individual Level + +* "`I built X investigations using this`" +* "`I got a job/promotion because of my portfolio`" +* "`I feel more confident in my work`" +* "`I charge more for my skills`" + +==== Community Level + +* X journalists active in program +* Y investigations published +* Z news organizations using methods +* Community self-sustaining (teaches each other) + +==== Systemic Level + +* PROMPT adopted as standard +* Interactive investigations normalized +* Journalism programs teach this +* Journalists feel hope, not doom + +''''' + +=== Key References & Inspiration + +==== Interactive Documentary (i-Docs) + +* i-Docs research network (i-docs.org) +* Korsakow system (non-linear documentary software) +* Notable projects: Out My Window, Hollow, Welcome to Pine Point, Prison +Valley + +==== Cognitive Science + +* Cowan (2001): Working memory limits +* Schwartz: Choice paralysis +* Rozenblit & Keil: Illusion of explanatory depth +* Kahan: Cultural cognition +* Nickerson: Understanding disagreement + +==== Boundary Objects + +* Susan Leigh Star: Objects that coordinate without consensus +* Maintain coherence across communities +* Enable collaboration while respecting difference + +==== Epistemology + +* PROMPT Framework (Provenance, Relevance, Objectivity, Methods, +Perspective, Timeliness) +* 27 philosophers across 9 subdisciplines +* Dempster-Shafer theory (uncertainty quantification) +* Pragmatic epistemology for public communication + +==== Participatory Communication + +* Nico Carpentier: Participation theory +* Democratic accessibility +* Audiences as co-creators + +''''' + +=== Contact & Collaboration + +*Project Lead*: Jonathan (NUJ connection, PhD candidate under Nico +Carpentier) + +*Looking For*: - Beta-testing journalists (especially demoralized ones!) +- Academic partners (journalism schools, media studies) - Funders +(Knight Foundation, Omidyar Network, European Media & Information Fund) +- Developers (especially: SvelteKit, PostgreSQL, D3.js) - i-Docs +practitioners - Cognitive scientists interested in epistemic interfaces + +*Philosophy*: Build in public, open source from day one, collaborative +not competitive. + +''''' + +_Last Updated: 2025-11-23_ _Status: Conceptual design → Moving to +proof-of-concept_ _Next Milestone: Week 1 deliverables (Level 1 +materials, evidence mapping template, one example investigation)_ diff --git a/claude.md b/claude.md deleted file mode 100644 index b8ba733..0000000 --- a/claude.md +++ /dev/null @@ -1,1128 +0,0 @@ - -# Wayfinder: Epistemic Infrastructure for Journalism - -## Project Vision - -**Wayfinder** is a heutagogic capability development pathway and interactive journalism framework designed to transform journalism from static truth-claims into navigable knowledge ecosystems. It addresses the fundamental challenge that data is outpacing knowledge, intelligence, and wisdom by making epistemological navigation itself the primary journalistic product. - -### Core Thesis - -We haven't moved from "Truth to Post-Truth" but from an era where knowledge systems were simpler to one where they're overwhelmed by data velocity. The solution isn't faster fact-checking—it's making truth-discovery processes transparent and navigable, not hidden behind editorial authority. - -## Conceptual Foundations - -### 1. The Knowledge Navigation Problem - -**Traditional Journalism**: "Here's what happened." -**Wayfinder Approach**: "Here's the evidence ecosystem. Navigate it. Understand how we know." - -This directly addresses that: -- Information velocity has exceeded sense-making capacity -- Trust in epistemic authorities has collapsed (often for good reasons) -- Different communities have developed different truth-testing procedures -- No shared infrastructure exists for collective intelligence - -### 2. Boundary Objects Theory (Susan Leigh Star) - -Wayfinder investigations function as **boundary objects** that: -- Maintain coherence across different communities -- Adapt to local needs without losing identity -- Enable coordination without requiring consensus -- Make visible what each community values -- Create shared infrastructure while respecting difference - -**Example**: The same evidence structure serves: -- **Activists**: Tool for mobilization ("What action should I take?") -- **Policymakers**: Decision support ("What are trade-offs?") -- **Academics**: Research resource ("What's the methodology?") -- **Skeptics**: Challenge mechanism ("Show me what's wrong") -- **Affected Communities**: Validation ("How does this affect people like me?") -- **Journalists**: Living investigation ("What's the story?") - -All work with the SAME evidence but interpret/use it differently. This bridges post-truth by creating coordination infrastructure, not forcing consensus. - -### 3. PROMPT Framework - -**P**rovenance - Who said it? What's their track record? -**R**elevance - Does this actually address the claim? -**O**bjectivity - What biases exist? Are they disclosed? -**M**ethods - How was this evidence gathered? Is it sound? -**P**erspective - What viewpoints are represented? What's missing? -**T**imeliness - Is this current? Has it been superseded? - -Each investigation assigns PROMPT scores to claims, making epistemic evaluation transparent. - -### 4. Data → Knowledge → Intelligence → Wisdom Pipeline - -Traditional journalism conflates all four levels. Wayfinder separates and makes each navigable: - -- **Data Layer**: Raw evidence, fully accessible -- **Knowledge Layer**: Structured claims with PROMPT analysis (what we can reliably say) -- **Intelligence Layer**: Pattern recognition, contradiction identification, gap analysis (what connections mean) -- **Wisdom Layer**: Practical reasoning for decision-making (what to do about it) - -## Architecture: Living Stories as Knowledge Graphs - -### Core Components - -#### 1. The Claim Layer -- Every piece starts with explicit, testable claims -- Each claim carries PROMPT scores visible to readers -- Claims are nodes that link to their evidence networks -- Statistical uncertainty is native (Dempster-Shafer intervals, not false certainty) - -#### 2. The Evidence Substrate -- Primary sources become explorable objects, not cited footnotes -- Korsakow-style "smallest narrative units" but for journalism: - - Original documents (OCR'd, searchable, annotatable) - - Interview segments (timestamped, transcribed, cross-referenced) - - Statistical data (interactive, methodology exposed) - - Expert analysis (credentials visible, conflicts flagged) - - Contradictory evidence explicitly included - -#### 3. The Methodology Transparency Layer -- Show editorial process: "We contacted 15 sources. Here's who responded, declined, or was unreachable" -- Expose reasoning chains: Not "experts say X" but "Expert A (credentials, biases) argues X because Y, based on methodology Z" -- Make PROMPT analysis visible -- Statistical reasoning exposed: Dempster-Shafer calculations, confidence intervals, assumptions - -#### 4. The Multi-Perspectival Navigation System -- Readers choose paths through evidence based on their questions -- Not "choose your own truth" but "explore from different epistemic starting points" -- Shows where perspectives converge (strong evidence) and diverge (genuine uncertainty vs. motivated reasoning) - -#### 5. The Collaborative Knowledge Layer -- Readers with expertise can annotate (credentials/reputation visible) -- Wikipedia's talk pages meets peer review -- New evidence can be submitted, triggering re-analysis -- Story evolves as living document, version history fully transparent - -## Cognitive Science & Design Principles - -### The Cognitive Load Paradox - -**Problem**: Interactive systems can create cognitive overload when trying to reduce epistemic confusion. - -**Evidence**: -- Working Memory Limits (Cowan, 2001): ~4 chunks actively processed -- Choice Paralysis (Schwartz): More options → decision paralysis -- Illusion of Explanatory Depth: People think they understand better when they can interact - -**Design Mitigations**: - -1. **Progressive Disclosure Architecture** - - Start with 3-5 essential claims maximum - - Each click reveals one level deeper, not everything - - "You're at depth 2 of 5" - make navigation cost visible - - Exit ramps at every level - -2. **Cognitive Scaffolding Through Curated Paths** - - Offer 3-4 "recommended paths" (guided museum tours) - - Only after completing one: "Explore freely" - - Respects spacing effect (distributed practice beats cramming) - -3. **Meta-Cognitive Prompts** - - "Before exploring, what would change your mind?" - - "You've spent 15 mins on confirming evidence, 2 mins contradicting - explore more?" - - Make reader's cognitive strategy visible to themselves - -4. **Active Retrieval Integration** - - Every 3-5 steps: "What's your understanding so far?" - - Converts navigation into learning, not just browsing - -### The Motivated Reasoning Problem - -**Problem**: Confirmation bias + selective navigation = echo chambers within your own tool. - -**Evidence**: -- Kahan's Cultural Cognition: People process evidence through identity-protective lenses -- Myside Bias: Better at finding flaws in opposing arguments -- Backfire Effect: Contradicting evidence can strengthen prior beliefs - -**Design Mitigations**: - -1. **Transparent Navigation Analytics** - - "You've viewed 12 pieces of evidence. 10 support X, 2 challenge it" - - "This pattern is common for people who believe X" (reflective, not judgmental) - - Gamification: "Completionist badge: Explored all major perspectives" - -2. **Empathy-First Contradictory Evidence** - - Before showing contradictions, humanize them - - "People who believe Y often do so because..." (steel man, not straw man) - -3. **Pre-Commitment Mechanisms** - - "What evidence would change your mind?" (before seeing evidence) - - Creates psychological commitment to epistemic openness - -4. **Collaborative Annotation with Adversaries** - - Partner readers with opposing views (opt-in) - - Explore together, see agreements/disagreements - - Social interaction reduces abstraction, increases humility - -### The Trust Calibration Challenge - -**Problem**: How much to trust the system? Too much = uncritical acceptance. Too little = ignores good evidence. - -**Design Mitigations**: - -1. **Calibrated Confidence Display** - - Not just "PROMPT score 0.7" but "Similar to [known reliable/unreliable] stories" - - "Stories with this evidence structure: X% accuracy rate" - -2. **Editor's Uncertainty Log** - - "I couldn't verify X despite Y attempts" - - "This source has Z credibility because..." - - Humanizes process, shows effort - -3. **Competing Analyses** - - For controversial topics: 2-3 independent journalistic teams - - Same evidence base, different PROMPT analyses - - Show convergence (high confidence) vs. divergence (genuine uncertainty) - -## Bio-Psycho-Social-Technical Systems Analysis - -### Biological Layer: Attention & Perception - -**Constraints**: -- Attentional Blink: Miss second target if 200-500ms after first -- Change Blindness: Miss large changes if attention elsewhere -- Visual Processing: ~10M bits/sec input, ~40 bits/sec conscious - -**Design Implications**: -- Max 3 active interactive zones per screen -- Use motion sparingly (draws involuntary attention) -- Critical info persistent, not transient -- Mobile-first (attention more fractured) -- Dual-coding (Paivio): Present claims verbally AND visually - -### Psychological Layer: Identity & Sensemaking - -**Key Insight**: People protect coherent self-narratives, not just evaluate evidence. - -**Threats**: -- System makes users feel stupid → defensive rejection -- Violates group identity → social cost too high -- Creates existential anxiety → denial/avoidance - -**Design Interventions**: - -1. **Face-Saving Architecture** - - Never "You were wrong" → "Evidence changed" or "Additional context emerged" - - "Smart people disagree" (normalize uncertainty) - - Celebrate updating: "Epistemic flexibility badge" - -2. **Identity-Safe Framings** (Kahan) - - Don't make issues identity-diagnostic if avoidable - - Frame climate as "energy security + innovation" not "believe science or be denier" - - Let users enter from their values, arrive at evidence - -3. **Narrative Coherence Support** - - People need stories, not just data - - Include paths maintaining coherence while updating beliefs - - "How to change your mind without losing your story" - -### Social Layer: Collective Sensemaking - -**Opportunities**: - -1. **Visible Cross-Cutting Exposure** - - "People who share view on X often agree on Y, disagree on Z" - - Show unexpected alliances (libertarians + progressives on surveillance) - -2. **Collaborative Investigation Features** - - Small groups (4-6) explore together - - Mix of perspectives encouraged - - Shared annotation creates common ground - -3. **Bridging Figures** - - Highlight experts/journalists trusted across divides - - Not "neutral" but "respected by multiple sides" - -4. **Network Analysis Transparency** - - "1M people shared this. Here's who: [demographics]" - - "Went viral in networks X, Y, but not Z - why?" - -### Technical Layer: Infrastructure Requirements - -**Critical Requirements**: - -1. **Accessibility** (Democratic accessibility principle) - - Screen reader compatible - - Text-only fallback - - Low-bandwidth version - - Translatable (i18n from day one) - -2. **Archival Permanence** - - Static site generation where possible - - No link rot (archive all sources) - - Version control everything - - IPFS/Arweave for permanence? - -3. **Algorithm Transparency** - - Any ranking/sorting explainable - - No hidden personalization (or fully disclosed) - - Open source where possible - -4. **Data Sovereignty** - - Users own annotations/navigation data - - Export anytime - - No surveillance capitalism - -## SWOT Analysis - -### Strengths -- **Epistemological Rigor**: PROMPT + philosophical framework provides theoretical foundation -- **Handles Genuine Uncertainty**: Embraces complexity honestly, doesn't pretend certainty -- **Scalable Complexity**: More complex topics → richer navigation, not just longer articles -- **Process Transparency**: Shows work, builds trust through visibility -- **Living Documents**: Updates as evidence evolves without "corrections" shame -- **Multi-Perspectival Without Relativism**: Different viewpoints without "all views equal" -- **Educational Value**: Users learn epistemic literacy by doing - -### Weaknesses -- **Production Cost**: 10x more work than traditional article (initially) -- **Requires New Skills**: Journalists need training in knowledge architecture, stats, design -- **User Learning Curve**: Audiences trained on passive consumption -- **Can't Cover Breaking News**: Too slow for "what happened today" -- **Vulnerability to Bad Faith**: Sophisticated actors could game the system -- **Maintenance Burden**: Living documents need tending -- **Cognitive Overhead**: Risks overwhelming users despite best design -- **Measurement Difficulty**: Hard to prove it's working - -### Opportunities -- **Institutional Support**: Knight Foundation, Craig Newmark Philanthropies fund innovation -- **Academic Partnerships**: PhD programs need practical outputs -- **NUJ Endorsement**: Professional legitimacy -- **Open Source Community**: Build in public, attract contributors -- **Journalism Crisis**: Desperation creates openness to experiment -- **Platform Exhaustion**: Audiences tired of social media epistemology -- **AI Literacy Movement**: Growing appetite for understanding information systems -- **Policy Interest**: Governments seeking misinformation solutions -- **Educational Adoption**: Universities teach media literacy with it -- **i-Docs Connection**: Built-in community and expertise - -### Threats -- **Economic Reality**: No obvious business model -- **Platform Competition**: Social media optimized for engagement, not truth -- **Attention Economy**: Fighting for scarce cognitive resource -- **Political Resistance**: Some actors benefit from confusion -- **Technical Debt**: Building custom systems vs. commercial tools -- **Perfectionism Trap**: Can't launch until "perfect" -- **Scope Creep**: Feature requests could bloat system -- **Burnout Risk**: One person with PhD to finish -- **Coordination Costs**: Multi-institution collaboration is hard -- **Measurement/Proof Problem**: Hard to prove impact, may lose funding - -## Heutagogic Learning Pathway - -### Core Principle -Journalists are demoralized, seeing "the end of journalism." They need self-determined learning with rapid proof-of-value through mastery experiences. - -**Not**: "Here's a new system to learn!" -**Instead**: "You have capabilities MORE valuable in information chaos. Build something that proves it." - -### The Four Capability Levels - -#### Level 1: "Skeptical Journalist" → Evidence Mapper -**Time**: 4-8 hours -**Output**: Single evidence-mapped claim -**Skill**: Provenance auditing - -**Challenge**: "Take one claim you're reporting. Just one. Map its evidence." - -**Process**: -1. Choose claim (something you're working on anyway) -2. List evidence (what you already have) -3. Score provenance (P from PROMPT - just this dimension) -4. Visualize (simple text list or hand-drawn sketch) -5. Reflect: "What did I discover?" - -**Reward**: -- Stronger sourcing for your article -- Spotted gaps to fill -- Better editor pitches: "Verified through X independent sources" -- More rigorous defense of reporting - -**Portfolio**: "I can identify strongest/weakest evidence parts" - -#### Level 2A: "Methodological Journalist" → Process Documentarian -**Time**: 8-12 hours -**Output**: Methodology transparency appendix -**Skill**: Scientific reasoning - -**Challenge**: "Show HOW you investigated, not just WHAT you found." - -**What You Build**: Methodology appendix documenting: -- Research questions (primary + secondary) -- Sources consulted (attempted, successful, declined, unavailable) -- Documents reviewed (primary sources, secondary analysis, contradictory evidence) -- Methodological choices (why these sources? what's missing? assumptions? contradictions?) -- Confidence assessment (evidence strength, certainty level, what would change this?) -- Timeline (when you discovered what) - -**Reward**: -- Editors love rigor, reduces liability -- Builds reader trust -- Improves quality (notice gaps while reporting) -- Professional development -- Competitive advantage - -**Portfolio**: "I practice transparent methodology journalism" - -#### Level 2B: "Statistical Journalist" → Uncertainty Communicator -**Time**: 6-10 hours -**Output**: Claims with honest confidence intervals -**Skill**: Statistical reasoning for journalism - -**Challenge**: "Replace false certainty with honest uncertainty that's more trustworthy." - -**Example Transformation**: -- **Bad**: "Inflation is 5%." -- **Good**: "Inflation reported at 5%, but: - - Uses CPI methodology (excludes X) - - Margin of error ±0.2% - - National average (regional: 3.8%-6.3%) - - Doesn't capture lived experience of [groups]" - -**Reward**: -- More accurate than journalists pretending certainty -- Readers trust you more (research confirms) -- Avoid errors (understanding uncertainty → fewer corrections) -- Future-proof (where journalism must go) - -**Portfolio**: "I communicate uncertainty responsibly" - -#### Level 3: "Interactive Journalist" → Knowledge Architect -**Time**: 20-40 hours (spread over weeks) -**Output**: Fully interactive evidence-based investigation -**Skill**: Non-linear narrative design - -**Challenge**: "Create a living investigation readers navigate, not just read." - -**Components** (modular, choose what you need): -- Core Claims Graph (3-7 main claims) -- Evidence Library (all sources, categorized) -- Methodology Transparency Page -- Multiple Entry Points (3-4 perspectives) -- Statistical Reasoning Exhibits (for numerical claims) -- Contradiction Acknowledgment (what doesn't fit) -- Update Log (as story evolves) -- Contribution Interface (how others add evidence) - -**Three Paths**: -- **Path A**: Convert existing story -- **Path B**: New investigation from scratch -- **Path C**: Collaborative (2-3 journalists, shared evidence base) - -**Reward**: -- Unique portfolio piece (no other journalist has this) -- Demonstrates future skills -- Actual impact (readers understand complex topics better) -- Professional recognition (conferences, awards, jobs) -- Personal satisfaction - -**Critical**: YOU choose the topic. Your passion = better output. - -#### Level 4: "Systems Journalist" → Epistemic Infrastructure Builder -**Time**: Ongoing practice -**Output**: Multiple investigations, teaching others, building tools -**Skill**: Meta-capability (learning to learn) - -**Challenge**: "You've mastered the method. Now evolve it." - -**Activities** (self-chosen): -- **Build**: Create new tools/templates for community -- **Teach**: Run workshops for other journalists -- **Research**: Write about methodology, publish findings -- **Advocate**: Push for institutional adoption -- **Innovate**: Invent new approaches to epistemic problems - -**Reward**: -- You're a pioneer (defining journalism's future) -- You're employable (rare, valuable skills) -- You're autonomous (work independently) -- You have meaning (solving real problems) -- You build legacy (training next generation) - -### Heutagogic Architecture: Self-Determination Mechanisms - -#### 1. Multiple Entry Points -Quiz: "Which sounds like you?" -- "I'm skeptical but curious" → Level 1 -- "I want to be more rigorous" → Level 2A -- "I'm bad at numbers but want to improve" → Level 2B -- "I want to build something new" → Level 3 -- "I already do some of this" → Skip-ahead assessment - -#### 2. Self-Paced Progression -- No deadlines, cohorts, or pressure -- "Most journalists spend 6 hours at Level 1" -- "Do this in one day or over a month" -- "Pause and return anytime" -- "Repeat levels to practice" - -#### 3. Choice Architecture -At every decision point: -- Show 3-4 options -- Show consequences (what you'll learn/build) -- Show escape routes ("Not ready? Try this instead") -- Show connections ("Relates to X you already know") - -#### 4. Reflection Prompts (Meta-Learning) -After each level: -- "What was harder than expected?" -- "What was easier?" -- "What will you do differently?" -- "What did you learn about your own learning?" - -Builds capability (not just competency). - -#### 5. Peer Learning (Optional) -- Buddy system: Pair journalists at same level -- Show and tell: Share work-in-progress -- Critique circles: 3-4 people review each other -- Expert office hours: Weekly drop-in - -All optional. Introverts can learn alone. - -#### 6. Portfolio Building (Visible Progress) -Each journalist maintains capability portfolio showing: -- Evidence mapping examples -- Methodology transparency exhibits -- Statistical journalism pieces -- Interactive investigations -- Tools created -- Skills checklist - -LinkedIn-able, hireable, provable value. - -## "Gamified by Results" Reward System - -### Intrinsic Rewards (What Actually Motivates Professionals) - -1. **Competence** (Mastery Experience) - - "I can do something I couldn't before" - - Each level proves new capability - - Feedback immediate and real - -2. **Autonomy** (Self-Direction) - - "I chose this path" - - No one forced me - - I control pace and focus - -3. **Purpose** (Meaningful Impact) - - "This matters" - - Builds better journalism - - Serves democracy - - Helps other journalists - -4. **Progress** (Visible Growth) - - Portfolio shows trajectory - - Compare early vs. recent work - - "I've come far" - -### Extrinsic Rewards (Secondary but Useful) - -1. **Professional Recognition** - - Certificate: "Epistemic Journalism Practitioner" - - "Knowledge Architect" credential (backed by NUJ?) - - Listed in public directory - - Speaking opportunities - -2. **Economic Value** - - "I can charge more for this work" - - "I got hired because of my portfolio" - - "My pitches succeed more often" - -3. **Peer Status** - - "Other journalists ask me to teach them" - - "I'm invited to conferences" - - "Editors request me specifically" - -4. **Competitive Advantage** - - "I have skills others don't" - - "I'm future-proof" - - "AI can't do what I do" - -### Results-Based "Unlocks" (Not Arbitrary Points) - -**After Level 1**: -- "Evidence mapper" credential -- Access to private journalist community -- Work featured in showcase -- Can mentor newcomers (if you want) - -**After Level 2A or 2B**: -- "Methodological journalist" credential -- Advanced templates and tools -- Guest post on methodology blog -- Can contribute to tool development - -**After Level 3**: -- "Knowledge architect" credential -- Investigation in featured gallery -- Conference speaking opportunities -- Can apply for grants/funding -- Job board access (orgs seeking these skills) - -**After Level 4**: -- "Epistemic infrastructure builder" credential -- Co-author research papers -- Shape future of system -- Revenue share from tools you create - -Each unlock genuinely valuable, not symbolic. - -## Demoralization → Hope Transition Strategy - -### Initial Contact: Meet Them in Their Despair - -**Don't start with**: "Here's a new system to learn!" - -**Start with**: "Journalism isn't dying. It's evolving. You have the capability to lead that evolution." - -### The Pitch (for demoralized journalists) - -"You're right that traditional journalism is struggling. But the problem isn't journalism—it's that we're using 20th-century methods for 21st-century information chaos. - -What if the skills you already have—investigation, verification, source development—are actually MORE valuable now, not less? What if you could develop capabilities that AI can't replicate and audiences desperately need? - -I'm building a pathway for journalists to develop these capabilities. Not a course. Not a tool. A self-directed learning journey where you build real investigations that demonstrate these skills while you learn them. - -It takes 4 hours to see if this resonates. If it doesn't, you've lost nothing. If it does, you've started building a portfolio that makes you uniquely valuable. - -Want to try?" - -### Early Win Engineering (Critical First 8 Hours) - -**Hour 1-2**: Watch examples -- See 3 interactive investigations -- Notice what's different -- "Could I build this?" - -**Hour 3-6**: Build Level 1 evidence map -- Use story you're already working on -- Apply PROMPT to one claim -- See value immediately - -**Hour 7-8**: Share and reflect -- Show to colleague or editor -- Get feedback -- Decide: continue or not? - -**Success metric**: "After 8 hours, do you think: 'This might be valuable' vs. 'This is pointless'" - -If yes → They'll self-direct from there. -If no → Wrong time or wrong fit (no pressure). - -### Community-Building (Combat Isolation) - -**Weekly Sync** (Optional): -- 90-minute video call -- Show and tell: "Here's what I built" -- Problem-solving: "Here's where I'm stuck" -- Teaching: "Here's what I learned" - -**Async Community**: -- Forum/Discord/Slack -- Share work-in-progress -- Ask questions -- Celebrate achievements - -**In-Person Gatherings** (Quarterly): -- One-day workshop -- Deep dive on advanced topics -- Guest speakers -- Networking - -**The Magic**: Demoralized journalists discover they're not alone. Others are figuring this out too. - -## Technical Implementation - -### Phase 1: Proof of Concept (NOW - 3 months) - -**Tools You Can Use Immediately**: - -1. **Obsidian Publish + Dataview Plugin** - - Graph database-lite (markdown files with frontmatter) - - Bidirectional links (evidence ↔ claims) - - Query language for dynamic views - - Publishable as static site - - Cost: $8/month hosting - - Advantage: Local-first, portable, no vendor lock-in - -2. **TiddlyWiki with Stroll Plugin** - - Single-file wiki (3MB, runs offline) - - Backlinks, transclusion, tags - - Zettelkasten-style navigation - - Cost: Free, self-hostable - - Advantage: Archival permanence, zero dependencies - -3. **Notion Public Pages** - - Databases with relations - - Multiple views (list, gallery, timeline) - - Embeds, comments - - Cost: Free tier workable - - Disadvantage: Proprietary, not archival - -**Prototype Structure**: - -Choose ONE complex story (e.g., "UK inflation crisis 2023") - -Create: -- 5-7 core claims (nodes) -- 20-30 evidence pieces (documents, interviews, data) -- 3 curated navigation paths -- PROMPT scores for each claim -- Methodology transparency page -- Multiple entry points - -Measure: -- Time to navigate -- Paths taken -- Where users get stuck -- Comprehension tests -- Attitude change - -Test With: -- 5 NUJ journalists (can they build it?) -- 5 academics (do they trust it?) -- 5 activists (do they find it useful?) -- 5 skeptics (can they critique it?) -- 5 "normal" readers (is it accessible?) - -### Phase 2: Custom Platform (3-9 months) - -If proof-of-concept works: - -**Technology Stack** (Respecting preferences): - -Backend: -- Python (FastAPI or Django) -- PostgreSQL (with pg_graphql for graph queries) -- MinIO (S3-compatible storage) -- Redis (caching) -- Celery (background tasks) - -Frontend: -- SvelteKit (better DX than React, progressive enhancement) -- TailwindCSS (utility-first styling) -- D3.js (evidence graph visualization) -- Marked (Markdown → HTML) - -Infrastructure: -- Podman for containerization -- GitLab CI/CD -- Self-hosted or Hetzner (EU data sovereignty) - -Key Features: -- Evidence graph editor -- PROMPT scoring workflow -- Multi-path navigation -- Annotation system -- Version control (git-like for content) -- Export/archive functionality - -**Progressive Enhancement Philosophy**: -- Works with JavaScript disabled (readable, navigable) -- Enhanced with JS (interactive graphs, animations) -- Respects prefers-reduced-motion -- Degrades gracefully - -### Phase 3: Ecosystem Building (9-18 months) - -**Community Infrastructure**: - -1. **Journalist Training Program** - - 3-day intensive: epistemology, PROMPT framework, tool usage - - Partner with NUJ for certification - - Create "Knowledge Architect" credential - -2. **Open Source Tools** - - PROMPT scorer (standalone) - - Evidence graph generator - - Statistical reasoning visualizer - - Release as modular components - -3. **Example Investigations** (Portfolio) - - Climate: "What do we know about 1.5°C targets?" - - Economics: "UK inflation causes: competing explanations" - - Health: "Long COVID evidence assessment" - - Local: "Town planning controversy: all evidence" - - Each demonstrates different features - -4. **Academic Integration** - - Partner with journalism schools - - PhD students do investigations as dissertations - - Published in new "Journal of Interactive Investigations" - -5. **Funding Diversification** - - Knight Foundation grants (they fund exactly this) - - Omidyar Network (investigative journalism) - - European Media & Information Fund - - University research funding - - Institutional subscriptions (news orgs pay to use platform) - -### Phase 4: Scaling & Sustainability (18+ months) - -**Network Effects**: - -1. **Evidence Commons** - - Investigations link to each other's evidence - - Build shared fact base - - Reduces duplication - -2. **Methodology Standardization** - - PROMPT becomes industry standard - - Like "fact-checked" but deeper - - "PROMPT-verified investigation" - -3. **API & Embeds** - - Other news sites embed your evidence graphs - - NPR story links to your evidence infrastructure - - Create distributed ecosystem - -4. **Institutional Adoption** - - BBC produces one interactive investigation - - Guardian has "Interactive Evidence" section - - ProPublica uses platform for exposés - -## Critical Success Factors - -### 1. Start Small, Prove Value -- One story, done excellently >> ten stories half-done -- Measure impact: comprehension, trust, behavior change -- Publish methodology + results - -### 2. Build in Public -- Document everything on GitLab -- Weekly dev logs -- Open source from day one -- Invite collaboration - -### 3. Respect Cognitive Limits -- Test with real users constantly -- Simplify relentlessly -- Kill features that confuse - -### 4. Maintain Epistemic Humility -- Your system can be wrong -- Show its limitations explicitly -- Welcome criticism -- Update based on evidence - -### 5. Create Beautiful Failures -- Some investigations will reveal: "We don't know" -- This is success, not failure -- Normalize uncertainty - -### 6. Partner, Don't Compete -- Not trying to replace traditional journalism -- Complementary tool -- Collaborate with news orgs - -## Boundary Object Implementation Strategy - -**Make This EXPLICIT in Design**: - -**Homepage Text**: - -"This investigation serves different purposes for different communities. Choose your path: - -- **Want to take action?** See implications and what you can do -- **Making policy?** Explore trade-offs and decision frameworks -- **Researching?** Dive into methodology and data -- **Skeptical?** Challenge our evidence and reasoning -- **Affected by this?** Find relevant local impacts -- **Fellow journalist?** See sources and newsworthiness - -All paths use the same evidence. All are valid. You can switch paths anytime." - -This normalizes plurality while maintaining evidential unity. - -## PhD Integration - -This IS the thesis: - -**Literature Review**: Heutagogy, cognitive ergonomics, boundary objects, epistemology - -**Design Research**: Building and testing the system - -**Action Research**: Working with practicing journalists - -**Evaluation**: Measuring impact on practice - -**Theoretical Contribution**: "Pragmatic epistemology for public communication" instantiated - -### PhD Outputs: -- Thesis: Theory + methodology + findings -- Working system: Demonstrates theory in practice -- Trained journalists: Evidence of impact -- Published investigations: Exemplars -- Tools/frameworks: Transferable artifacts - -### Nico Carpentier Alignment - -Perfectly aligns with participatory communication theory: -- Journalists as co-creators (not just authorities) -- Audiences as active participants (not passive consumers) -- Democratic accessibility through capability development -- Pre-Truth to Truth argument embedded (system shows how truth is constructed) -- Boundary objects enable coordination without consensus - -## Implementation Timeline - -### Month 1-2: Foundation -- Build Level 1 materials -- Create 2 example investigations -- Set up basic website -- Recruit 5 beta testers (NUJ contacts) - -### Month 3-4: First Cohort -- 10-15 journalists go through Level 1 -- Gather feedback -- Iterate materials -- Build Level 2A materials - -### Month 5-6: Expansion -- Launch Level 2B -- First Level 3 investigations produced -- Case studies published -- Media coverage - -### Month 7-9: Community -- Self-organizing study groups -- First Level 4 practitioners -- Tools being shared -- Institutional interest - -### Month 10-12: Sustainability -- Revenue model established -- Community mostly self-managing -- Focus on research/innovation -- System works autonomously - -## The Philosophical Payoff - -### Thesis Argument Strengthens: - -**Not**: "We fell from Truth to Post-Truth" - -**But**: "We evolved from simple epistemology to complex epistemology without building the infrastructure" - -### Wayfinder IS That Infrastructure - -It embodies: -- PROMPT framework (practical epistemology) -- 27-philosopher synthesis (theoretical depth) -- Statistical methods (honest uncertainty) -- Democratic accessibility principle (epistemic justice) -- The i-docs insight (navigation over narration) -- Boundary objects theory (coordination without consensus) - -It's not just a tool. It's a working model of **pragmatic epistemology for public communication**. - -And crucially: **It's buildable now**. With existing technologies. With existing skills and networks. Within PhD timeframes. - -## Next Steps: Starting This Week - -### Week 1: -- Document Level 1 pathway (8-10 pages) -- Create evidence mapping template -- Build one example investigation (use existing project) - -### Week 2: -- Share with 3 journalist friends -- "Will you try this for 4 hours and give me feedback?" -- Iterate based on responses - -### Week 3: -- Build simple website (GitLab Pages) -- Write recruitment pitch -- Post in NUJ channels - -### Week 4: -- First 5-10 participants start -- Support them through Level 1 -- Document what works/doesn't - -**You're 4 weeks from proof-of-concept.** - ---- - -## Branding & Messaging - -### Primary Name: Wayfinder - -**Why This Works**: - -1. **Solves Demoralization**: "You're not obsolete—you're a Wayfinder. People need guides who show them HOW to navigate complexity, not just WHAT to believe." - -2. **Boundary Object Name**: Different communities hear what they need: - - Journalists: "I help people find their way through complex stories" - - Academics: "Wayfinding through epistemic complexity" - - Funders: "Teaching information navigation skills" - - Public: "Guides who show you how to understand complex issues" - -3. **Scales Beautifully**: - - The investigations: "Wayfinder investigations" - - The journalists: "I'm a Wayfinder" or "Wayfinder journalist" - - The training: "Wayfinder learning pathway" - - The credentials: "Certified Wayfinder" / "Wayfinder practitioner" - -4. **Gamification-Friendly**: - - Level 1: Apprentice Wayfinder - - Level 2: Journeyman Wayfinder - - Level 3: Master Wayfinder - - Level 4: Wayfinder Architect - -### Tagline Options: -- "Wayfinder: Navigate complexity, build understanding" -- "Wayfinder: Journalism for the journey from data to wisdom" -- "Wayfinder: Guides through information complexity" -- "Wayfinder: Building navigable knowledge" - -### Elevator Pitch: - -"Wayfinder trains journalists to create navigable investigations—living, interactive evidence structures that help readers find their way through complex, contested topics. It's not just better journalism; it's journalism rebuilt for epistemic complexity." - -### For Demoralized Journalists: - -"You're not obsolete. You're needed more than ever—but as Wayfinders, not gatekeepers. People need guides who show them HOW to navigate complexity, not just WHAT to believe. Wayfinder gives you the capabilities to be that guide." - ---- - -## Institutional Angle (For Sustainability) - -### Pitch to News Organizations: - -"Your journalists are demoralized because they feel obsolete. They're not. But they need new capabilities. - -For [£X/month per journalist], we provide: -- Self-paced capability development -- Tools and templates -- Community support -- Portfolio building -- Credentialing - -Results: -- Higher-quality investigations -- Methodological rigor (reduces liability) -- Competitive advantage in market -- Improved morale and retention -- Future-proof skills - -No mandates. Journalists opt-in. You see who's engaged." - -This funds development while serving journalists. - ---- - -## Platform: Minimal Viable Infrastructure - -**Core**: Simple website (Hugo/Jekyll static site) -**Content**: Markdown files (portable, future-proof) -**Hosting**: GitLab Pages (free, version controlled) -**Learning paths**: Embedded in content, not LMS -**Community**: Discord or Discourse (free tiers) -**Portfolio hosting**: Personal GitHub/GitLab pages - -**Total cost**: ~£0-20/month at start - ---- - -## Content Creation Strategy: Build With, Not For - -**You create**: -- Level 1 materials (evidence mapping basics) -- Framework documentation (PROMPT) -- Example investigations (2-3 different topics) -- Templates (Notion, Obsidian, Markdown) - -**Community creates** (Level 4 participants): -- Additional examples -- Specialized tools -- Domain-specific guides -- Translations -- Improvements - -This scales WITHOUT you doing everything. - ---- - -## Measuring Success - -### Individual Level -- "I built X investigations using this" -- "I got a job/promotion because of my portfolio" -- "I feel more confident in my work" -- "I charge more for my skills" - -### Community Level -- X journalists active in program -- Y investigations published -- Z news organizations using methods -- Community self-sustaining (teaches each other) - -### Systemic Level -- PROMPT adopted as standard -- Interactive investigations normalized -- Journalism programs teach this -- Journalists feel hope, not doom - ---- - -## Key References & Inspiration - -### Interactive Documentary (i-Docs) -- i-Docs research network (i-docs.org) -- Korsakow system (non-linear documentary software) -- Notable projects: Out My Window, Hollow, Welcome to Pine Point, Prison Valley - -### Cognitive Science -- Cowan (2001): Working memory limits -- Schwartz: Choice paralysis -- Rozenblit & Keil: Illusion of explanatory depth -- Kahan: Cultural cognition -- Nickerson: Understanding disagreement - -### Boundary Objects -- Susan Leigh Star: Objects that coordinate without consensus -- Maintain coherence across communities -- Enable collaboration while respecting difference - -### Epistemology -- PROMPT Framework (Provenance, Relevance, Objectivity, Methods, Perspective, Timeliness) -- 27 philosophers across 9 subdisciplines -- Dempster-Shafer theory (uncertainty quantification) -- Pragmatic epistemology for public communication - -### Participatory Communication -- Nico Carpentier: Participation theory -- Democratic accessibility -- Audiences as co-creators - ---- - -## Contact & Collaboration - -**Project Lead**: Jonathan (NUJ connection, PhD candidate under Nico Carpentier) - -**Looking For**: -- Beta-testing journalists (especially demoralized ones!) -- Academic partners (journalism schools, media studies) -- Funders (Knight Foundation, Omidyar Network, European Media & Information Fund) -- Developers (especially: SvelteKit, PostgreSQL, D3.js) -- i-Docs practitioners -- Cognitive scientists interested in epistemic interfaces - -**Philosophy**: Build in public, open source from day one, collaborative not competitive. - ---- - -*Last Updated: 2025-11-23* -*Status: Conceptual design → Moving to proof-of-concept* -*Next Milestone: Week 1 deliverables (Level 1 materials, evidence mapping template, one example investigation)* diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..c33f8c0 --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,71 @@ +== Tech-Debt Audit — im-docs — 2026-05-26 + +*Source:* estate-wide automated scan 2026-05-26. *Companion:* +https://github.com/hyperpolymath/standards/tree/main/docs/audits[`+hyperpolymath/standards+` +2026-05-26-estate-*-debt audits]. *Combined severity:* `+MEDIUM+`. + +This file records the _raw findings_ — it does not by itself fix the +debt. Each section ends with a '`Recommended next move`' line; closing +the debt is follow-up work. + +=== 1. Proof debt + +No proof-bearing files (`+*.v+`, `+*.lean+`, `+*.agda+`, `+*.idr+`, +`+*.idr2+`, `+*.fst+`, `+*.dfy+`, `+*.tla+`, `+*.ads+`, `+*.adb+`) found +in this repo. + +*Recommended next move:* none. + +=== 2. Licence debt + +[cols=",",options="header",] +|=== +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+MPL-2.0+` +|Manifest licence |`+NONE+` +|Body classifier |`+Palimp-MPL-2.0+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |177 +|`+docs/+` files |3 +|`+docs/+` LoC |296 +|CHANGELOG.md |N +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+MEDIUM+` +|=== + +*Recommended next move:* introduce a `+docs/+` directory. The README at +177 lines has likely grown to do the work of `+docs/+` — split it into a +thin README + `+docs/architecture.md+`, `+docs/usage.md+`, etc. +Heavy-wiki exemplars to copy from: `+affinescript+`, `+boj-server+`, +`+echidna+`, `+hypatia+`. + +Additionally: *CHANGELOG.md is missing.* 65% of estate repos lack one — +adopting a CHANGELOG (or auto-generating via `+git-cliff+`) is a +recommended estate-wide follow-up. + +=== Cross-references + +* Estate proof-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md+` +* Estate licence-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md+` +* Estate documentation-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md+` + +''''' + +🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). +This file is informational — closing the debt is follow-up work owned by +the maintainer. diff --git a/docs/tech-debt-2026-05-26.md b/docs/tech-debt-2026-05-26.md deleted file mode 100644 index 97d591c..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,56 +0,0 @@ - -# Tech-Debt Audit — im-docs — 2026-05-26 - -**Source:** estate-wide automated scan 2026-05-26. -**Companion:** [`hyperpolymath/standards` 2026-05-26-estate-*-debt audits](https://github.com/hyperpolymath/standards/tree/main/docs/audits). -**Combined severity:** `MEDIUM`. - -This file records the *raw findings* — it does not by itself fix the debt. Each section ends with a 'Recommended next move' line; closing the debt is follow-up work. - -## 1. Proof debt - -No proof-bearing files (`*.v`, `*.lean`, `*.agda`, `*.idr`, `*.idr2`, `*.fst`, `*.dfy`, `*.tla`, `*.ads`, `*.adb`) found in this repo. - -**Recommended next move:** none. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `MPL-2.0` | -| Manifest licence | `NONE` | -| Body classifier | `Palimp-MPL-2.0` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 177 | -| `docs/` files | 3 | -| `docs/` LoC | 296 | -| CHANGELOG.md | N | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `MEDIUM` | - -**Recommended next move:** introduce a `docs/` directory. The README at 177 lines has likely grown to do the work of `docs/` — split it into a thin README + `docs/architecture.md`, `docs/usage.md`, etc. Heavy-wiki exemplars to copy from: `affinescript`, `boj-server`, `echidna`, `hypatia`. - -Additionally: **CHANGELOG.md is missing.** 65% of estate repos lack one — adopting a CHANGELOG (or auto-generating via `git-cliff`) is a recommended estate-wide follow-up. - -## Cross-references - -- Estate proof-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md` -- Estate licence-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md` -- Estate documentation-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md` - ---- - -🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). This file is informational — closing the debt is follow-up work owned by the maintainer. diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..a0d845c --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — im-docs (Developer) + +=== What is im-docs? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-dev.md b/llm-warmup-dev.md deleted file mode 100644 index 8e9500a..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — im-docs (Developer) - -## What is im-docs? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.adoc b/llm-warmup-user.adoc new file mode 100644 index 0000000..1ae54f4 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — im-docs (User) + +=== What is im-docs? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.md b/llm-warmup-user.md deleted file mode 100644 index 0a7336f..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — im-docs (User) - -## What is im-docs? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture