diff --git a/STATE.scm b/STATE.scm new file mode 100644 index 0000000..32508fc --- /dev/null +++ b/STATE.scm @@ -0,0 +1,368 @@ +;;; STATE.scm — Fogbinder Project State Checkpoint +;;; Format: Guile Scheme S-expressions +;;; Purpose: Context reconstruction across conversation boundaries + +(define-module (fogbinder state) + #:export (state)) + +;;;; ============================================================ +;;;; METADATA +;;;; ============================================================ + +(define metadata + '((format-version . "1.0.0") + (project . "fogbinder") + (created . "2025-12-08") + (last-updated . "2025-12-08") + (schema . "state.scm/v1"))) + +;;;; ============================================================ +;;;; PROJECT SUMMARY +;;;; ============================================================ + +(define project-summary + '((name . "Fogbinder") + (tagline . "Zotero plugin for navigating epistemic ambiguity in research") + (philosophy . ("Late Wittgenstein: Language games, family resemblance" + "J.L. Austin: Speech act theory, illocutionary force")) + (core-insight . "Ambiguity and contradiction are features to explore, not bugs to fix") + (tech-stack . ((primary . "ReScript") + (performance . "Rust/WASM") + (runtime . "Deno") + (target . "Zotero 7.0+ plugin"))))) + +;;;; ============================================================ +;;;; CURRENT POSITION +;;;; ============================================================ + +(define current-position + '((overall-completion . "80%") + (phase . "pre-mvp") + (status . "in-progress") + + (implemented + ((core-philosophy + ((module . "EpistemicState.res") + (status . "complete") + (tested . #t) + (description . "6 epistemic modalities: Known, Probable, Vague, Ambiguous, Mysterious, Contradictory")) + ((module . "SpeechAct.res") + (status . "complete") + (tested . #t) + (description . "J.L. Austin's 5 illocutionary forces with felicity conditions")) + ((module . "FamilyResemblance.res") + (status . "complete") + (tested . #t) + (description . "Wittgensteinian clustering without strict definitions"))) + + (analysis-engines + ((module . "ContradictionDetector.res") + (status . "complete") + (tested . #f) + (description . "Detects language-game conflicts (5 types)")) + ((module . "MoodScorer.res") + (status . "complete") + (tested . #f) + (description . "Speech-act-based mood analysis")) + ((module . "MysteryClustering.res") + (status . "complete") + (tested . #f) + (description . "Clusters epistemic resistance (4 types)")) + ((module . "FogTrailVisualizer.res") + (status . "complete") + (tested . #f) + (description . "Network visualization with SVG/JSON export"))) + + (orchestration + ((module . "Fogbinder.res") + (status . "complete") + (tested . #t) + (description . "Main analysis pipeline, batch processing, report generation")) + ((module . "main.js") + (status . "complete") + (tested . #f) + (description . "JavaScript API wrapper with JSDoc types"))))) + + (partial + ((wasm-modules + ((module . "contradiction_detector") + (status . "stubbed") + (description . "Language game conflict detection - TODOs remain")) + ((module . "graph_algorithms") + (status . "stubbed") + (description . "Force-directed layout, fog density, community detection")) + ((module . "string_similarity") + (status . "stubbed") + (description . "Cosine/Jaccard similarity not implemented")) + ((module . "crypto") + (status . "partial") + (description . "SHAKE256/BLAKE3 working; Ed448/Kyber need implementation"))) + + (zotero-integration + ((module . "ZoteroBindings.res") + (status . "complete") + (description . "ReScript bindings defined")) + ((module . "zotero_api.js") + (status . "mock-only") + (description . "Uses mock data, needs real Zotero API integration"))))) + + (not-implemented + ("Actual WASM compilation (Cargo modules set up but not building)" + "TypeScript elimination (src/main.ts still exists)" + "npm removal (still uses Node.js for ReScript compiler)" + "Full Zotero integration (currently uses mock data)" + "Benchmarking suite (infrastructure removed in migration)" + "Advanced NLP (currently simplified heuristics)" + "Formal verification (placeholder directory, no proofs)")))) + +;;;; ============================================================ +;;;; ROUTE TO MVP v1 +;;;; ============================================================ + +(define mvp-route + '((version . "1.0.0") + (target-scope . "Functional Zotero plugin with core analysis features") + + (critical-path + ((step . 1) + (task . "Real Zotero Integration") + (description . "Replace mock data in zotero_api.js with actual Zotero API calls") + (files . ("src/zotero/zotero_api.js" "src/zotero/ZoteroBindings.res")) + (priority . "P0") + (blockers . none)) + + ((step . 2) + (task . "Test Coverage for Engine Modules") + (description . "Add tests for ContradictionDetector, MoodScorer, MysteryClustering, FogTrailVisualizer") + (files . ("src/engines/*.res")) + (priority . "P0") + (blockers . none)) + + ((step . 3) + (task . "Build Pipeline Verification") + (description . "Ensure ReScript compilation works end-to-end, verify all .bs.js outputs") + (priority . "P0") + (blockers . none)) + + ((step . 4) + (task . "Manual Integration Testing") + (description . "Test with real Zotero library, verify analysis accuracy") + (priority . "P0") + (blockers . (1 2 3))) + + ((step . 5) + (task . "Zotero Plugin Packaging") + (description . "Create proper .xpi file for Zotero installation") + (files . ("manifest.json")) + (priority . "P0") + (blockers . (4)))) + + (deferred-to-post-mvp + ("WASM modules compilation and integration" + "Post-quantum cryptography (Ed448, Kyber-1024)" + "Advanced NLP models" + "Formal verification proofs" + "Benchmarking suite" + "Full localization support" + "Performance optimization")))) + +;;;; ============================================================ +;;;; KNOWN ISSUES +;;;; ============================================================ + +(define issues + '((blocking + ((id . "ISS-001") + (severity . "high") + (title . "Zotero API Integration is Mocked") + (description . "zotero_api.js returns mock data, not connected to real Zotero") + (impact . "Plugin cannot function with real research libraries") + (location . "src/zotero/zotero_api.js")) + + ((id . "ISS-002") + (severity . "high") + (title . "Engine Modules Lack Test Coverage") + (description . "ContradictionDetector, MoodScorer, MysteryClustering, FogTrailVisualizer have no tests") + (impact . "Cannot verify correctness of analysis outputs") + (location . "src/engines/"))) + + (non-blocking + ((id . "ISS-003") + (severity . "medium") + (title . "WASM Modules Not Compiled") + (description . "Rust WASM modules are stubbed with TODOs, Cargo not building") + (impact . "Performance optimization unavailable, using pure JS fallbacks") + (location . "src/wasm/")) + + ((id . "ISS-004") + (severity . "medium") + (title . "TypeScript File Still Exists") + (description . "src/main.ts should be removed or converted to ReScript") + (impact . "Inconsistent with stated 'no TypeScript' architecture") + (location . "src/main.ts")) + + ((id . "ISS-005") + (severity . "low") + (title . "Simplified NLP Heuristics") + (description . "Mood scoring and contradiction detection use string matching, not proper NLP") + (impact . "Analysis accuracy limited, may miss subtle contradictions") + (location . "src/engines/")) + + ((id . "ISS-006") + (severity . "low") + (title . "Post-Quantum Crypto Incomplete") + (description . "Ed448 signing and Kyber-1024 KEM have TODOs") + (impact . "Security features not fully available") + (location . "src/wasm/crypto/src/lib.rs"))))) + +;;;; ============================================================ +;;;; QUESTIONS FOR MAINTAINER +;;;; ============================================================ + +(define questions + '(((id . "Q-001") + (topic . "MVP Scope") + (question . "Should MVP include any WASM modules, or is pure ReScript/JS acceptable for v1?") + (context . "WASM provides performance but adds complexity; JS-only is simpler to ship")) + + ((id . "Q-002") + (topic . "Zotero API") + (question . "Do you have a Zotero test library set up for integration testing?") + (context . "Need real data to test plugin functionality")) + + ((id . "Q-003") + (topic . "NLP Strategy") + (question . "For v1, should we keep simplified heuristics or integrate a proper NLP library?") + (context . "Current string-matching is fast but less accurate; NLP adds dependencies")) + + ((id . "Q-004") + (topic . "Distribution") + (question . "Will this be distributed via Zotero's official plugin registry or self-hosted?") + (context . "Affects packaging, signing, and update mechanism requirements")) + + ((id . "Q-005") + (topic . "Priority") + (question . "What's the relative priority: accuracy of analysis vs. completeness of visualization?") + (context . "Could focus effort on either ContradictionDetector accuracy OR FogTrail polish")) + + ((id . "Q-006") + (topic . "Security") + (question . "Is post-quantum crypto required for MVP, or can it wait for v1.1?") + (context . "Current usage is unclear; may be over-engineered for research tool")))) + +;;;; ============================================================ +;;;; LONG-TERM ROADMAP +;;;; ============================================================ + +(define roadmap + '((v1.0 . ((name . "MVP Release") + (focus . "Core functionality in Zotero") + (features . ("Real Zotero API integration" + "Contradiction detection" + "Mood scoring" + "Mystery clustering" + "FogTrail visualization" + "Basic report generation")) + (tech-debt . "Simplified heuristics, no WASM, mock removal"))) + + (v1.1 . ((name . "Performance & Polish") + (focus . "Speed optimization and UX refinement") + (features . ("WASM module integration (graph algorithms)" + "Improved FogTrail interactivity" + "Batch processing optimization" + "Error handling improvements" + "User preferences persistence")))) + + (v1.2 . ((name . "Advanced Analysis") + (focus . "Better NLP and analysis accuracy") + (features . ("Proper NLP integration for mood/contradiction" + "Configurable sensitivity thresholds" + "Custom language game definitions" + "Export to citation managers beyond Zotero")))) + + (v2.0 . ((name . "Collaborative Research") + (focus . "Multi-user and sharing features") + (features . ("Shared FogTrail annotations" + "Team contradiction discussions" + "Post-quantum signed attestations" + "Research trail versioning" + "API for external integrations")))) + + (v3.0 . ((name . "AI-Augmented Ambiguity") + (focus . "LLM integration for deeper analysis") + (features . ("LLM-powered contradiction explanation" + "Suggested resolution strategies" + "Cross-corpus mystery detection" + "Automated literature review assistance" + "Philosophical stance classification")))))) + +;;;; ============================================================ +;;;; ARCHITECTURE NOTES +;;;; ============================================================ + +(define architecture-notes + '((data-flow . "Sources → EpistemicState → Analysis Engines → FogTrail → Report") + + (layer-stack . ("Zotero Plugin Interface (manifest.json)" + "API Layer (main.js)" + "Orchestration (Fogbinder.res)" + "Analysis Engines (ReScript)" + "Core Philosophy (ReScript)" + "Performance (Rust/WASM, optional)")) + + (key-types . ((EpistemicModality . "Known | Probable | Vague | Ambiguous | Mysterious | Contradictory") + (IllocutionaryForce . "Assertive | Directive | Commissive | Expressive | Declaration") + (ContradictionType . "DirectNegation | MethodologicalConflict | TerminologicalDispute | PresuppositionClash | LanguageGameConflict") + (MysteryType . "Phenomenological | Conceptual | Empirical | Methodological"))) + + (philosophy-encoding . "Wittgenstein's 'whereof one cannot speak' as Mysterious modality; Austin's performatives as first-class types"))) + +;;;; ============================================================ +;;;; NEXT ACTIONS (PRIORITIZED) +;;;; ============================================================ + +(define next-actions + '(((priority . 1) + (action . "Implement real Zotero API calls in zotero_api.js") + (rationale . "Unblocks all integration testing")) + + ((priority . 2) + (action . "Write tests for ContradictionDetector.res") + (rationale . "Core analysis feature, needs verification")) + + ((priority . 3) + (action . "Write tests for MoodScorer.res") + (rationale . "Speech act analysis is philosophically central")) + + ((priority . 4) + (action . "Write tests for MysteryClustering.res") + (rationale . "Completes engine test coverage")) + + ((priority . 5) + (action . "Verify ReScript build produces valid Zotero-compatible bundle") + (rationale . "Must work in Zotero's XUL/WebExtension environment")) + + ((priority . 6) + (action . "Create .xpi packaging script") + (rationale . "Required for Zotero installation")) + + ((priority . 7) + (action . "Remove or convert src/main.ts") + (rationale . "Architectural consistency with 'no TypeScript' stance")))) + +;;;; ============================================================ +;;;; STATE EXPORT +;;;; ============================================================ + +(define state + `((metadata . ,metadata) + (project-summary . ,project-summary) + (current-position . ,current-position) + (mvp-route . ,mvp-route) + (issues . ,issues) + (questions . ,questions) + (roadmap . ,roadmap) + (architecture-notes . ,architecture-notes) + (next-actions . ,next-actions))) + +;;; End of STATE.scm