|
| 1 | +;;; STATE.scm — Fogbinder Project State Checkpoint |
| 2 | +;;; Format: Guile Scheme S-expressions |
| 3 | +;;; Purpose: Context reconstruction across conversation boundaries |
| 4 | + |
| 5 | +(define-module (fogbinder state) |
| 6 | + #:export (state)) |
| 7 | + |
| 8 | +;;;; ============================================================ |
| 9 | +;;;; METADATA |
| 10 | +;;;; ============================================================ |
| 11 | + |
| 12 | +(define metadata |
| 13 | + '((format-version . "1.0.0") |
| 14 | + (project . "fogbinder") |
| 15 | + (created . "2025-12-08") |
| 16 | + (last-updated . "2025-12-08") |
| 17 | + (schema . "state.scm/v1"))) |
| 18 | + |
| 19 | +;;;; ============================================================ |
| 20 | +;;;; PROJECT SUMMARY |
| 21 | +;;;; ============================================================ |
| 22 | + |
| 23 | +(define project-summary |
| 24 | + '((name . "Fogbinder") |
| 25 | + (tagline . "Zotero plugin for navigating epistemic ambiguity in research") |
| 26 | + (philosophy . ("Late Wittgenstein: Language games, family resemblance" |
| 27 | + "J.L. Austin: Speech act theory, illocutionary force")) |
| 28 | + (core-insight . "Ambiguity and contradiction are features to explore, not bugs to fix") |
| 29 | + (tech-stack . ((primary . "ReScript") |
| 30 | + (performance . "Rust/WASM") |
| 31 | + (runtime . "Deno") |
| 32 | + (target . "Zotero 7.0+ plugin"))))) |
| 33 | + |
| 34 | +;;;; ============================================================ |
| 35 | +;;;; CURRENT POSITION |
| 36 | +;;;; ============================================================ |
| 37 | + |
| 38 | +(define current-position |
| 39 | + '((overall-completion . "80%") |
| 40 | + (phase . "pre-mvp") |
| 41 | + (status . "in-progress") |
| 42 | + |
| 43 | + (implemented |
| 44 | + ((core-philosophy |
| 45 | + ((module . "EpistemicState.res") |
| 46 | + (status . "complete") |
| 47 | + (tested . #t) |
| 48 | + (description . "6 epistemic modalities: Known, Probable, Vague, Ambiguous, Mysterious, Contradictory")) |
| 49 | + ((module . "SpeechAct.res") |
| 50 | + (status . "complete") |
| 51 | + (tested . #t) |
| 52 | + (description . "J.L. Austin's 5 illocutionary forces with felicity conditions")) |
| 53 | + ((module . "FamilyResemblance.res") |
| 54 | + (status . "complete") |
| 55 | + (tested . #t) |
| 56 | + (description . "Wittgensteinian clustering without strict definitions"))) |
| 57 | + |
| 58 | + (analysis-engines |
| 59 | + ((module . "ContradictionDetector.res") |
| 60 | + (status . "complete") |
| 61 | + (tested . #f) |
| 62 | + (description . "Detects language-game conflicts (5 types)")) |
| 63 | + ((module . "MoodScorer.res") |
| 64 | + (status . "complete") |
| 65 | + (tested . #f) |
| 66 | + (description . "Speech-act-based mood analysis")) |
| 67 | + ((module . "MysteryClustering.res") |
| 68 | + (status . "complete") |
| 69 | + (tested . #f) |
| 70 | + (description . "Clusters epistemic resistance (4 types)")) |
| 71 | + ((module . "FogTrailVisualizer.res") |
| 72 | + (status . "complete") |
| 73 | + (tested . #f) |
| 74 | + (description . "Network visualization with SVG/JSON export"))) |
| 75 | + |
| 76 | + (orchestration |
| 77 | + ((module . "Fogbinder.res") |
| 78 | + (status . "complete") |
| 79 | + (tested . #t) |
| 80 | + (description . "Main analysis pipeline, batch processing, report generation")) |
| 81 | + ((module . "main.js") |
| 82 | + (status . "complete") |
| 83 | + (tested . #f) |
| 84 | + (description . "JavaScript API wrapper with JSDoc types"))))) |
| 85 | + |
| 86 | + (partial |
| 87 | + ((wasm-modules |
| 88 | + ((module . "contradiction_detector") |
| 89 | + (status . "stubbed") |
| 90 | + (description . "Language game conflict detection - TODOs remain")) |
| 91 | + ((module . "graph_algorithms") |
| 92 | + (status . "stubbed") |
| 93 | + (description . "Force-directed layout, fog density, community detection")) |
| 94 | + ((module . "string_similarity") |
| 95 | + (status . "stubbed") |
| 96 | + (description . "Cosine/Jaccard similarity not implemented")) |
| 97 | + ((module . "crypto") |
| 98 | + (status . "partial") |
| 99 | + (description . "SHAKE256/BLAKE3 working; Ed448/Kyber need implementation"))) |
| 100 | + |
| 101 | + (zotero-integration |
| 102 | + ((module . "ZoteroBindings.res") |
| 103 | + (status . "complete") |
| 104 | + (description . "ReScript bindings defined")) |
| 105 | + ((module . "zotero_api.js") |
| 106 | + (status . "mock-only") |
| 107 | + (description . "Uses mock data, needs real Zotero API integration"))))) |
| 108 | + |
| 109 | + (not-implemented |
| 110 | + ("Actual WASM compilation (Cargo modules set up but not building)" |
| 111 | + "TypeScript elimination (src/main.ts still exists)" |
| 112 | + "npm removal (still uses Node.js for ReScript compiler)" |
| 113 | + "Full Zotero integration (currently uses mock data)" |
| 114 | + "Benchmarking suite (infrastructure removed in migration)" |
| 115 | + "Advanced NLP (currently simplified heuristics)" |
| 116 | + "Formal verification (placeholder directory, no proofs)")))) |
| 117 | + |
| 118 | +;;;; ============================================================ |
| 119 | +;;;; ROUTE TO MVP v1 |
| 120 | +;;;; ============================================================ |
| 121 | + |
| 122 | +(define mvp-route |
| 123 | + '((version . "1.0.0") |
| 124 | + (target-scope . "Functional Zotero plugin with core analysis features") |
| 125 | + |
| 126 | + (critical-path |
| 127 | + ((step . 1) |
| 128 | + (task . "Real Zotero Integration") |
| 129 | + (description . "Replace mock data in zotero_api.js with actual Zotero API calls") |
| 130 | + (files . ("src/zotero/zotero_api.js" "src/zotero/ZoteroBindings.res")) |
| 131 | + (priority . "P0") |
| 132 | + (blockers . none)) |
| 133 | + |
| 134 | + ((step . 2) |
| 135 | + (task . "Test Coverage for Engine Modules") |
| 136 | + (description . "Add tests for ContradictionDetector, MoodScorer, MysteryClustering, FogTrailVisualizer") |
| 137 | + (files . ("src/engines/*.res")) |
| 138 | + (priority . "P0") |
| 139 | + (blockers . none)) |
| 140 | + |
| 141 | + ((step . 3) |
| 142 | + (task . "Build Pipeline Verification") |
| 143 | + (description . "Ensure ReScript compilation works end-to-end, verify all .bs.js outputs") |
| 144 | + (priority . "P0") |
| 145 | + (blockers . none)) |
| 146 | + |
| 147 | + ((step . 4) |
| 148 | + (task . "Manual Integration Testing") |
| 149 | + (description . "Test with real Zotero library, verify analysis accuracy") |
| 150 | + (priority . "P0") |
| 151 | + (blockers . (1 2 3))) |
| 152 | + |
| 153 | + ((step . 5) |
| 154 | + (task . "Zotero Plugin Packaging") |
| 155 | + (description . "Create proper .xpi file for Zotero installation") |
| 156 | + (files . ("manifest.json")) |
| 157 | + (priority . "P0") |
| 158 | + (blockers . (4)))) |
| 159 | + |
| 160 | + (deferred-to-post-mvp |
| 161 | + ("WASM modules compilation and integration" |
| 162 | + "Post-quantum cryptography (Ed448, Kyber-1024)" |
| 163 | + "Advanced NLP models" |
| 164 | + "Formal verification proofs" |
| 165 | + "Benchmarking suite" |
| 166 | + "Full localization support" |
| 167 | + "Performance optimization")))) |
| 168 | + |
| 169 | +;;;; ============================================================ |
| 170 | +;;;; KNOWN ISSUES |
| 171 | +;;;; ============================================================ |
| 172 | + |
| 173 | +(define issues |
| 174 | + '((blocking |
| 175 | + ((id . "ISS-001") |
| 176 | + (severity . "high") |
| 177 | + (title . "Zotero API Integration is Mocked") |
| 178 | + (description . "zotero_api.js returns mock data, not connected to real Zotero") |
| 179 | + (impact . "Plugin cannot function with real research libraries") |
| 180 | + (location . "src/zotero/zotero_api.js")) |
| 181 | + |
| 182 | + ((id . "ISS-002") |
| 183 | + (severity . "high") |
| 184 | + (title . "Engine Modules Lack Test Coverage") |
| 185 | + (description . "ContradictionDetector, MoodScorer, MysteryClustering, FogTrailVisualizer have no tests") |
| 186 | + (impact . "Cannot verify correctness of analysis outputs") |
| 187 | + (location . "src/engines/"))) |
| 188 | + |
| 189 | + (non-blocking |
| 190 | + ((id . "ISS-003") |
| 191 | + (severity . "medium") |
| 192 | + (title . "WASM Modules Not Compiled") |
| 193 | + (description . "Rust WASM modules are stubbed with TODOs, Cargo not building") |
| 194 | + (impact . "Performance optimization unavailable, using pure JS fallbacks") |
| 195 | + (location . "src/wasm/")) |
| 196 | + |
| 197 | + ((id . "ISS-004") |
| 198 | + (severity . "medium") |
| 199 | + (title . "TypeScript File Still Exists") |
| 200 | + (description . "src/main.ts should be removed or converted to ReScript") |
| 201 | + (impact . "Inconsistent with stated 'no TypeScript' architecture") |
| 202 | + (location . "src/main.ts")) |
| 203 | + |
| 204 | + ((id . "ISS-005") |
| 205 | + (severity . "low") |
| 206 | + (title . "Simplified NLP Heuristics") |
| 207 | + (description . "Mood scoring and contradiction detection use string matching, not proper NLP") |
| 208 | + (impact . "Analysis accuracy limited, may miss subtle contradictions") |
| 209 | + (location . "src/engines/")) |
| 210 | + |
| 211 | + ((id . "ISS-006") |
| 212 | + (severity . "low") |
| 213 | + (title . "Post-Quantum Crypto Incomplete") |
| 214 | + (description . "Ed448 signing and Kyber-1024 KEM have TODOs") |
| 215 | + (impact . "Security features not fully available") |
| 216 | + (location . "src/wasm/crypto/src/lib.rs"))))) |
| 217 | + |
| 218 | +;;;; ============================================================ |
| 219 | +;;;; QUESTIONS FOR MAINTAINER |
| 220 | +;;;; ============================================================ |
| 221 | + |
| 222 | +(define questions |
| 223 | + '(((id . "Q-001") |
| 224 | + (topic . "MVP Scope") |
| 225 | + (question . "Should MVP include any WASM modules, or is pure ReScript/JS acceptable for v1?") |
| 226 | + (context . "WASM provides performance but adds complexity; JS-only is simpler to ship")) |
| 227 | + |
| 228 | + ((id . "Q-002") |
| 229 | + (topic . "Zotero API") |
| 230 | + (question . "Do you have a Zotero test library set up for integration testing?") |
| 231 | + (context . "Need real data to test plugin functionality")) |
| 232 | + |
| 233 | + ((id . "Q-003") |
| 234 | + (topic . "NLP Strategy") |
| 235 | + (question . "For v1, should we keep simplified heuristics or integrate a proper NLP library?") |
| 236 | + (context . "Current string-matching is fast but less accurate; NLP adds dependencies")) |
| 237 | + |
| 238 | + ((id . "Q-004") |
| 239 | + (topic . "Distribution") |
| 240 | + (question . "Will this be distributed via Zotero's official plugin registry or self-hosted?") |
| 241 | + (context . "Affects packaging, signing, and update mechanism requirements")) |
| 242 | + |
| 243 | + ((id . "Q-005") |
| 244 | + (topic . "Priority") |
| 245 | + (question . "What's the relative priority: accuracy of analysis vs. completeness of visualization?") |
| 246 | + (context . "Could focus effort on either ContradictionDetector accuracy OR FogTrail polish")) |
| 247 | + |
| 248 | + ((id . "Q-006") |
| 249 | + (topic . "Security") |
| 250 | + (question . "Is post-quantum crypto required for MVP, or can it wait for v1.1?") |
| 251 | + (context . "Current usage is unclear; may be over-engineered for research tool")))) |
| 252 | + |
| 253 | +;;;; ============================================================ |
| 254 | +;;;; LONG-TERM ROADMAP |
| 255 | +;;;; ============================================================ |
| 256 | + |
| 257 | +(define roadmap |
| 258 | + '((v1.0 . ((name . "MVP Release") |
| 259 | + (focus . "Core functionality in Zotero") |
| 260 | + (features . ("Real Zotero API integration" |
| 261 | + "Contradiction detection" |
| 262 | + "Mood scoring" |
| 263 | + "Mystery clustering" |
| 264 | + "FogTrail visualization" |
| 265 | + "Basic report generation")) |
| 266 | + (tech-debt . "Simplified heuristics, no WASM, mock removal"))) |
| 267 | + |
| 268 | + (v1.1 . ((name . "Performance & Polish") |
| 269 | + (focus . "Speed optimization and UX refinement") |
| 270 | + (features . ("WASM module integration (graph algorithms)" |
| 271 | + "Improved FogTrail interactivity" |
| 272 | + "Batch processing optimization" |
| 273 | + "Error handling improvements" |
| 274 | + "User preferences persistence")))) |
| 275 | + |
| 276 | + (v1.2 . ((name . "Advanced Analysis") |
| 277 | + (focus . "Better NLP and analysis accuracy") |
| 278 | + (features . ("Proper NLP integration for mood/contradiction" |
| 279 | + "Configurable sensitivity thresholds" |
| 280 | + "Custom language game definitions" |
| 281 | + "Export to citation managers beyond Zotero")))) |
| 282 | + |
| 283 | + (v2.0 . ((name . "Collaborative Research") |
| 284 | + (focus . "Multi-user and sharing features") |
| 285 | + (features . ("Shared FogTrail annotations" |
| 286 | + "Team contradiction discussions" |
| 287 | + "Post-quantum signed attestations" |
| 288 | + "Research trail versioning" |
| 289 | + "API for external integrations")))) |
| 290 | + |
| 291 | + (v3.0 . ((name . "AI-Augmented Ambiguity") |
| 292 | + (focus . "LLM integration for deeper analysis") |
| 293 | + (features . ("LLM-powered contradiction explanation" |
| 294 | + "Suggested resolution strategies" |
| 295 | + "Cross-corpus mystery detection" |
| 296 | + "Automated literature review assistance" |
| 297 | + "Philosophical stance classification")))))) |
| 298 | + |
| 299 | +;;;; ============================================================ |
| 300 | +;;;; ARCHITECTURE NOTES |
| 301 | +;;;; ============================================================ |
| 302 | + |
| 303 | +(define architecture-notes |
| 304 | + '((data-flow . "Sources → EpistemicState → Analysis Engines → FogTrail → Report") |
| 305 | + |
| 306 | + (layer-stack . ("Zotero Plugin Interface (manifest.json)" |
| 307 | + "API Layer (main.js)" |
| 308 | + "Orchestration (Fogbinder.res)" |
| 309 | + "Analysis Engines (ReScript)" |
| 310 | + "Core Philosophy (ReScript)" |
| 311 | + "Performance (Rust/WASM, optional)")) |
| 312 | + |
| 313 | + (key-types . ((EpistemicModality . "Known | Probable | Vague | Ambiguous | Mysterious | Contradictory") |
| 314 | + (IllocutionaryForce . "Assertive | Directive | Commissive | Expressive | Declaration") |
| 315 | + (ContradictionType . "DirectNegation | MethodologicalConflict | TerminologicalDispute | PresuppositionClash | LanguageGameConflict") |
| 316 | + (MysteryType . "Phenomenological | Conceptual | Empirical | Methodological"))) |
| 317 | + |
| 318 | + (philosophy-encoding . "Wittgenstein's 'whereof one cannot speak' as Mysterious modality; Austin's performatives as first-class types"))) |
| 319 | + |
| 320 | +;;;; ============================================================ |
| 321 | +;;;; NEXT ACTIONS (PRIORITIZED) |
| 322 | +;;;; ============================================================ |
| 323 | + |
| 324 | +(define next-actions |
| 325 | + '(((priority . 1) |
| 326 | + (action . "Implement real Zotero API calls in zotero_api.js") |
| 327 | + (rationale . "Unblocks all integration testing")) |
| 328 | + |
| 329 | + ((priority . 2) |
| 330 | + (action . "Write tests for ContradictionDetector.res") |
| 331 | + (rationale . "Core analysis feature, needs verification")) |
| 332 | + |
| 333 | + ((priority . 3) |
| 334 | + (action . "Write tests for MoodScorer.res") |
| 335 | + (rationale . "Speech act analysis is philosophically central")) |
| 336 | + |
| 337 | + ((priority . 4) |
| 338 | + (action . "Write tests for MysteryClustering.res") |
| 339 | + (rationale . "Completes engine test coverage")) |
| 340 | + |
| 341 | + ((priority . 5) |
| 342 | + (action . "Verify ReScript build produces valid Zotero-compatible bundle") |
| 343 | + (rationale . "Must work in Zotero's XUL/WebExtension environment")) |
| 344 | + |
| 345 | + ((priority . 6) |
| 346 | + (action . "Create .xpi packaging script") |
| 347 | + (rationale . "Required for Zotero installation")) |
| 348 | + |
| 349 | + ((priority . 7) |
| 350 | + (action . "Remove or convert src/main.ts") |
| 351 | + (rationale . "Architectural consistency with 'no TypeScript' stance")))) |
| 352 | + |
| 353 | +;;;; ============================================================ |
| 354 | +;;;; STATE EXPORT |
| 355 | +;;;; ============================================================ |
| 356 | + |
| 357 | +(define state |
| 358 | + `((metadata . ,metadata) |
| 359 | + (project-summary . ,project-summary) |
| 360 | + (current-position . ,current-position) |
| 361 | + (mvp-route . ,mvp-route) |
| 362 | + (issues . ,issues) |
| 363 | + (questions . ,questions) |
| 364 | + (roadmap . ,roadmap) |
| 365 | + (architecture-notes . ,architecture-notes) |
| 366 | + (next-actions . ,next-actions))) |
| 367 | + |
| 368 | +;;; End of STATE.scm |
0 commit comments